arckode-framework 1.1.0 → 1.1.1

package/kernel/framework.ts

@@ -1252,6 +1252,55 @@ export interface ServerAdapter {
   stop(): Promise<void>
 }
 
+// ── Envelope estándar de respuesta API ──────────────────────────
+// Todas las respuestas siguen este contrato. Un solo lugar para cambiar el formato.
+// Inspirado en JSend + convenciones de GitHub/Laravel:
+//   success → { success: true,  data: T,    meta: { pagination? } | null, error: null }
+//   error   → { success: false, data: null, meta: null,               error: { code, message, details } }
+export interface ApiResponse<T = unknown> {
+  success: boolean
+  data: T | null
+  meta: { pagination?: unknown } | null
+  error: { code: string; message: string; details?: unknown } | null
+}
+
+function buildEnvelope(status: number, body: unknown): string {
+  // Errores 4xx / 5xx
+  if (status >= 400) {
+    const b = (body ?? {}) as Record<string, unknown>
+    return JSON.stringify({
+      success: false,
+      data: null,
+      meta: null,
+      error: {
+        code:    b.code    ?? 'ERROR',
+        message: b.error   ?? 'Error',
+        details: b.details ?? null,
+      },
+    } satisfies ApiResponse)
+  }
+
+  // Sin contenido (DELETE 204)
+  if (body === null || body === undefined) {
+    return JSON.stringify({ success: true, data: null, meta: null, error: null } satisfies ApiResponse)
+  }
+
+  const b = body as Record<string, unknown>
+
+  // Lista paginada — el service retorna { data: [], pagination: {} }
+  if (Array.isArray(b.data) && b.pagination !== undefined) {
+    return JSON.stringify({
+      success: true,
+      data: b.data,
+      meta: { pagination: b.pagination },
+      error: null,
+    } satisfies ApiResponse)
+  }
+
+  // Recurso único o cualquier otro payload exitoso
+  return JSON.stringify({ success: true, data: body, meta: null, error: null } satisfies ApiResponse)
+}
+
 export class NodeServer implements ServerAdapter {
   private server?: ReturnType<typeof createNodeServer>
   private maxBodyBytes: number
@@ -1314,8 +1363,10 @@ export class NodeServer implements ServerAdapter {
 
             // ── Respuesta normal (JSON o binario comprimido) ──
             const isBuffer = Buffer.isBuffer(res.body)
-            const responseBody = isBuffer ? res.body : JSON.stringify(res.body)
-            nodeRes.writeHead(res.status, {
+            // 204 prohíbe body por spec HTTP — con envelope usamos 200 para "no content"
+            const effectiveStatus = res.status === 204 ? 200 : res.status
+            const responseBody = isBuffer ? res.body : buildEnvelope(effectiveStatus, res.body)
+            nodeRes.writeHead(effectiveStatus, {
               'Content-Type': 'application/json',
               'X-Request-Id': req.id,
               ...res.headers,
@@ -1325,13 +1376,13 @@ export class NodeServer implements ServerAdapter {
             const httpStatus = (error as any)?.httpStatus
             if (httpStatus) {
               nodeRes.writeHead(httpStatus, { 'Content-Type': 'application/json' })
-              nodeRes.end(JSON.stringify({ error: (error as Error).message, code: 'REQUEST_ERROR' }))
+              nodeRes.end(buildEnvelope(httpStatus, { error: (error as Error).message, code: 'REQUEST_ERROR' }))
               return
             }
             const stack = error instanceof Error ? error.stack : String(error)
             this.logger.error('Error no manejado en HTTP', { error: String(error), stack })
             nodeRes.writeHead(500, { 'Content-Type': 'application/json' })
-            nodeRes.end(JSON.stringify({ error: 'Error interno', code: 'INTERNAL_ERROR' }))
+            nodeRes.end(buildEnvelope(500, { error: 'Error interno', code: 'INTERNAL_ERROR' }))
           } finally {
             this.activeRequests--
           }
@@ -1968,6 +2019,6 @@ export default {
   // Seeds
   SeedRunner,
 
-  // Types (re-exported for convenience)
-  // All interfaces are exported above
+  // Response envelope
+  // ApiResponse interface is exported as named export above
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arckode-framework",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "AI-first TypeScript/Bun framework. Modular, SOLID, zero magic. The AI reads the composition root and knows everything.",
   "type": "module",
   "main": "./kernel/framework.ts",