create-tigra 2.1.4 → 2.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-tigra",
-  "version": "2.1.4",
+  "version": "2.1.5",
   "type": "module",
   "description": "Create a production-ready full-stack app with Next.js 16 + Fastify 5 + Prisma + Redis",
   "bin": {

package/template/_claude/rules/server/project-conventions.md

@@ -14,6 +14,7 @@
 | Redis | Caching (frequently accessed data, lookups), rate limiting, background task signaling |
 | Zod | Runtime validation and type inference |
 | JWT (HS256/RS256) | Auth — minimal token payload (id, role), role-based access control |
+| axios | Outbound HTTP client (external API calls) |
 | PM2 + Nginx | Production deployment (cluster mode) |
 | Jest / Vitest | Testing — deterministic, mock external APIs |
 
@@ -148,3 +149,66 @@ Collection Root (Bearer Token: {{accessToken}})
 - Never interpolate raw values into SQL — always use Prisma query builder
 - Rate limit public endpoints
 - Avoid N+1 queries — prefer joins or batched queries
+
+## Outbound HTTP
+
+Use `httpClient` from `src/libs/http.ts` for ALL outbound HTTP calls. Never use native `fetch`, `node:http`, or a new `axios.create()` at the call site — the singleton provides consistent logging, 30s timeout, and automatic error conversion.
+
+### Import
+
+```typescript
+import { httpClient } from '@libs/http.js';
+```
+
+### Wrapping pattern (service layer)
+
+Outbound HTTP calls belong in the **service layer**. The interceptor converts `AxiosError` to `InternalError` automatically — services only deal with `AppError` subclasses:
+
+```typescript
+class WeatherService {
+  async getCurrentWeather(city: string): Promise<WeatherData> {
+    const response = await httpClient.get<WeatherApiResponse>(
+      `https://api.weather.example.com/v1/current`,
+      { params: { q: city } },
+    );
+    return response.data.result;
+  }
+}
+export const weatherService = new WeatherService();
+```
+
+### Auth headers
+
+Do NOT add auth headers to the `httpClient` singleton — it is shared. Pass per-request headers at the call site:
+
+```typescript
+await httpClient.post(url, body, {
+  headers: { Authorization: `Bearer ${token}` },
+});
+```
+
+### Fine-grained error mapping
+
+The interceptor always throws `InternalError`. If you need a more specific error (e.g., a 404 from an external API should surface as `NotFoundError`), catch and rethrow:
+
+```typescript
+try {
+  return await httpClient.get(url);
+} catch {
+  throw new NotFoundError('External resource not found');
+}
+```
+
+### Fixed-base-URL services
+
+If a service always calls the same external API, create a private derived instance **inside the service file only** (never exported):
+
+```typescript
+const apiClient = axios.create({ ...httpClient.defaults, baseURL: 'https://api.example.com/v2' });
+```
+
+### Rules
+
+- Always use `httpClient` — never `fetch`, `node:http`, or inline `axios.create()`.
+- Never add auth headers, cookies, or credentials to the singleton itself.
+- Never log response bodies (may contain PII or secrets).

package/template/server/package.json

@@ -38,6 +38,7 @@
     "@fastify/static": "^9.0.0",
     "@prisma/client": "^6.19.2",
     "argon2": "^0.44.0",
+    "axios": "^1.7.9",
     "dotenv": "^16.4.7",
     "fastify": "^5.7.4",
     "fastify-type-provider-zod": "^6.1.0",

package/template/server/src/libs/__tests__/http.test.ts

@@ -0,0 +1,414 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { InternalAxiosRequestConfig, AxiosResponse } from 'axios';
+import { InternalError } from '@shared/errors/errors.js';
+
+// ---------------------------------------------------------------------------
+// Captured interceptor handlers (populated when http.ts is first imported)
+// vi.hoisted() ensures these are available inside the vi.mock factory
+// ---------------------------------------------------------------------------
+const captured = vi.hoisted(() => ({
+  requestFulfilled: null as null | ((c: InternalAxiosRequestConfig) => InternalAxiosRequestConfig),
+  requestRejected: null as null | ((e: unknown) => never),
+  responseFulfilled: null as null | ((r: AxiosResponse) => AxiosResponse),
+  responseRejected: null as null | ((e: unknown) => never),
+  mockIsAxiosError: vi.fn<(e: unknown) => boolean>(),
+}));
+
+// ---------------------------------------------------------------------------
+// Mock axios — captures interceptor handlers at registration time
+// ---------------------------------------------------------------------------
+vi.mock('axios', () => ({
+  default: {
+    create: vi.fn(() => ({
+      interceptors: {
+        request: {
+          use: vi.fn((onFulfilled: any, onRejected: any) => {
+            captured.requestFulfilled = onFulfilled;
+            captured.requestRejected = onRejected;
+          }),
+        },
+        response: {
+          use: vi.fn((onFulfilled: any, onRejected: any) => {
+            captured.responseFulfilled = onFulfilled;
+            captured.responseRejected = onRejected;
+          }),
+        },
+      },
+    })),
+  },
+  isAxiosError: captured.mockIsAxiosError,
+}));
+
+// ---------------------------------------------------------------------------
+// Mock logger — prevents real Pino I/O in tests
+// ---------------------------------------------------------------------------
+vi.mock('@libs/logger.js', () => ({
+  logger: {
+    debug: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+// Import AFTER mocks are registered
+import { httpClient } from '../http.js';
+import { logger } from '@libs/logger.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeConfig(overrides: Partial<InternalAxiosRequestConfig> = {}): InternalAxiosRequestConfig {
+  return { headers: {} as InternalAxiosRequestConfig['headers'], ...overrides };
+}
+
+function makeResponse(overrides: Partial<AxiosResponse> = {}): AxiosResponse {
+  return {
+    data: {},
+    status: 200,
+    statusText: 'OK',
+    headers: {},
+    config: makeConfig({ method: 'get', url: '/test' }),
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('httpClient', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    captured.mockIsAxiosError.mockReturnValue(false);
+  });
+
+  // -------------------------------------------------------------------------
+  // Module contract
+  // -------------------------------------------------------------------------
+  describe('module contract', () => {
+    it('should be exported as a named export', () => {
+      expect(httpClient).toBeDefined();
+    });
+
+    it('should return the same singleton instance on re-import', async () => {
+      const { httpClient: httpClient2 } = await import('../http.js');
+      expect(httpClient2).toBe(httpClient);
+    });
+
+    it('should have registered exactly one request interceptor', () => {
+      expect(captured.requestFulfilled).not.toBeNull();
+      expect(captured.requestRejected).not.toBeNull();
+    });
+
+    it('should have registered exactly one response interceptor', () => {
+      expect(captured.responseFulfilled).not.toBeNull();
+      expect(captured.responseRejected).not.toBeNull();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Request interceptor — success path
+  // -------------------------------------------------------------------------
+  describe('request interceptor (success)', () => {
+    it('should return the config unchanged', () => {
+      const config = makeConfig({ method: 'get', url: '/users' });
+      const result = captured.requestFulfilled!(config);
+      expect(result).toBe(config);
+    });
+
+    it('should log outbound request at debug level', () => {
+      const config = makeConfig({ method: 'get', url: '/users', baseURL: 'https://api.example.com' });
+      captured.requestFulfilled!(config);
+      expect(logger.debug).toHaveBeenCalledOnce();
+      expect(logger.debug).toHaveBeenCalledWith(
+        { method: 'GET', url: '/users', baseURL: 'https://api.example.com' },
+        '[HTTP] Outbound request',
+      );
+    });
+
+    it('should uppercase the HTTP method in the log', () => {
+      captured.requestFulfilled!(makeConfig({ method: 'post', url: '/items' }));
+      expect(logger.debug).toHaveBeenCalledWith(
+        expect.objectContaining({ method: 'POST' }),
+        '[HTTP] Outbound request',
+      );
+    });
+
+    it('should handle undefined method without throwing', () => {
+      const config = makeConfig({ url: '/noop' });
+      expect(() => captured.requestFulfilled!(config)).not.toThrow();
+      expect(logger.debug).toHaveBeenCalledWith(
+        expect.objectContaining({ method: undefined }),
+        '[HTTP] Outbound request',
+      );
+    });
+
+    it('should not call logger.error on the success path', () => {
+      captured.requestFulfilled!(makeConfig({ method: 'get', url: '/ok' }));
+      expect(logger.error).not.toHaveBeenCalled();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Request interceptor — error path
+  // -------------------------------------------------------------------------
+  describe('request interceptor (error)', () => {
+    it('should throw an InternalError', () => {
+      expect(() => captured.requestRejected!(new Error('setup fail'))).toThrow(InternalError);
+    });
+
+    it('should throw with the correct message', () => {
+      expect(() => captured.requestRejected!(new Error('x'))).toThrow(
+        'Outbound HTTP request could not be constructed',
+      );
+    });
+
+    it('should throw InternalError with statusCode 500', () => {
+      let thrown: unknown;
+      try {
+        captured.requestRejected!(new Error('x'));
+      } catch (e) {
+        thrown = e;
+      }
+      expect((thrown as InternalError).statusCode).toBe(500);
+    });
+
+    it('should throw InternalError with code INTERNAL_ERROR', () => {
+      let thrown: unknown;
+      try {
+        captured.requestRejected!(new Error('x'));
+      } catch (e) {
+        thrown = e;
+      }
+      expect((thrown as InternalError).code).toBe('INTERNAL_ERROR');
+    });
+
+    it('should log the error before throwing', () => {
+      const err = new Error('setup fail');
+      try {
+        captured.requestRejected!(err);
+      } catch {
+        // expected
+      }
+      expect(logger.error).toHaveBeenCalledWith({ err }, '[HTTP] Request setup failed');
+    });
+
+    it('should not call logger.debug on the error path', () => {
+      try {
+        captured.requestRejected!(new Error('x'));
+      } catch {
+        // expected
+      }
+      expect(logger.debug).not.toHaveBeenCalled();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Response interceptor — success path
+  // -------------------------------------------------------------------------
+  describe('response interceptor (success)', () => {
+    it('should return the response unchanged', () => {
+      const response = makeResponse({ status: 200, data: { id: 42 } });
+      const result = captured.responseFulfilled!(response);
+      expect(result).toBe(response);
+    });
+
+    it('should log the response at debug level', () => {
+      const response = makeResponse({
+        status: 201,
+        config: makeConfig({ method: 'post', url: '/items' }),
+      });
+      captured.responseFulfilled!(response);
+      expect(logger.debug).toHaveBeenCalledOnce();
+      expect(logger.debug).toHaveBeenCalledWith(
+        { method: 'POST', url: '/items', status: 201 },
+        '[HTTP] Outbound response',
+      );
+    });
+
+    it('should uppercase the HTTP method in the response log', () => {
+      const response = makeResponse({
+        config: makeConfig({ method: 'delete', url: '/items/1' }),
+      });
+      captured.responseFulfilled!(response);
+      expect(logger.debug).toHaveBeenCalledWith(
+        expect.objectContaining({ method: 'DELETE' }),
+        '[HTTP] Outbound response',
+      );
+    });
+
+    it('should not call logger.error on the success path', () => {
+      captured.responseFulfilled!(makeResponse());
+      expect(logger.error).not.toHaveBeenCalled();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Response interceptor — AxiosError path
+  // -------------------------------------------------------------------------
+  describe('response interceptor (AxiosError)', () => {
+    beforeEach(() => {
+      captured.mockIsAxiosError.mockReturnValue(true);
+    });
+
+    const buildAxiosError = (overrides: Record<string, unknown> = {}): object => ({
+      isAxiosError: true,
+      config: { method: 'get', url: '/failing', headers: {} },
+      response: { status: 503 },
+      message: 'Service Unavailable',
+      ...overrides,
+    });
+
+    it('should throw an InternalError', () => {
+      expect(() => captured.responseRejected!(buildAxiosError())).toThrow(InternalError);
+    });
+
+    it('should throw with the correct message', () => {
+      expect(() => captured.responseRejected!(buildAxiosError())).toThrow(
+        'Outbound HTTP request failed',
+      );
+    });
+
+    it('should throw InternalError with statusCode 500', () => {
+      let thrown: unknown;
+      try {
+        captured.responseRejected!(buildAxiosError());
+      } catch (e) {
+        thrown = e;
+      }
+      expect((thrown as InternalError).statusCode).toBe(500);
+    });
+
+    it('should throw InternalError with code INTERNAL_ERROR', () => {
+      let thrown: unknown;
+      try {
+        captured.responseRejected!(buildAxiosError());
+      } catch (e) {
+        thrown = e;
+      }
+      expect((thrown as InternalError).code).toBe('INTERNAL_ERROR');
+    });
+
+    it('should log method, url, status, and message', () => {
+      try {
+        captured.responseRejected!(
+          buildAxiosError({
+            config: { method: 'post', url: '/upload', headers: {} },
+            response: { status: 413 },
+            message: 'Payload Too Large',
+          }),
+        );
+      } catch {
+        // expected
+      }
+      expect(logger.error).toHaveBeenCalledWith(
+        { method: 'POST', url: '/upload', status: 413, message: 'Payload Too Large' },
+        '[HTTP] Outbound request failed',
+      );
+    });
+
+    it('should uppercase method in error log', () => {
+      try {
+        captured.responseRejected!(
+          buildAxiosError({ config: { method: 'delete', url: '/x', headers: {} } }),
+        );
+      } catch {
+        // expected
+      }
+      expect(logger.error).toHaveBeenCalledWith(
+        expect.objectContaining({ method: 'DELETE' }),
+        '[HTTP] Outbound request failed',
+      );
+    });
+
+    it('should handle missing config/response gracefully', () => {
+      const minimalError = { isAxiosError: true, message: 'timeout' };
+      expect(() => captured.responseRejected!(minimalError)).toThrow(InternalError);
+      expect(logger.error).toHaveBeenCalledWith(
+        { method: undefined, url: undefined, status: undefined, message: 'timeout' },
+        '[HTTP] Outbound request failed',
+      );
+    });
+
+    it('should not call logger.debug on the error path', () => {
+      try {
+        captured.responseRejected!(buildAxiosError());
+      } catch {
+        // expected
+      }
+      expect(logger.debug).not.toHaveBeenCalled();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Response interceptor — non-AxiosError path
+  // -------------------------------------------------------------------------
+  describe('response interceptor (non-AxiosError)', () => {
+    beforeEach(() => {
+      captured.mockIsAxiosError.mockReturnValue(false);
+    });
+
+    it('should throw an InternalError for a plain Error', () => {
+      expect(() => captured.responseRejected!(new Error('network failure'))).toThrow(InternalError);
+    });
+
+    it('should throw with the correct message', () => {
+      expect(() => captured.responseRejected!(new Error('x'))).toThrow(
+        'Outbound HTTP request failed',
+      );
+    });
+
+    it('should log with the generic message and err field', () => {
+      const err = new Error('network failure');
+      try {
+        captured.responseRejected!(err);
+      } catch {
+        // expected
+      }
+      expect(logger.error).toHaveBeenCalledWith({ err }, '[HTTP] Unexpected outbound error');
+    });
+
+    it('should throw InternalError for thrown string', () => {
+      expect(() => captured.responseRejected!('something broke')).toThrow(InternalError);
+    });
+
+    it('should throw InternalError for thrown null', () => {
+      expect(() => captured.responseRejected!(null)).toThrow(InternalError);
+    });
+
+    it('should not call logger.debug on the error path', () => {
+      try {
+        captured.responseRejected!(new Error('x'));
+      } catch {
+        // expected
+      }
+      expect(logger.debug).not.toHaveBeenCalled();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Security: sensitive data must NOT be logged
+  // -------------------------------------------------------------------------
+  describe('security: no sensitive data in logs', () => {
+    it('should not log request body in request interceptor', () => {
+      captured.requestFulfilled!(makeConfig({ method: 'post', url: '/login', data: { password: 'secret' } }));
+      const logCall = vi.mocked(logger.debug).mock.calls[0][0] as Record<string, unknown>;
+      expect(logCall).not.toHaveProperty('data');
+      expect(JSON.stringify(logCall)).not.toContain('secret');
+    });
+
+    it('should not log response body in response interceptor', () => {
+      captured.responseFulfilled!(makeResponse({ data: { token: 'bearer-xyz', password: 'hidden' } }));
+      const logCall = vi.mocked(logger.debug).mock.calls[0][0] as Record<string, unknown>;
+      expect(logCall).not.toHaveProperty('data');
+      expect(JSON.stringify(logCall)).not.toContain('bearer-xyz');
+    });
+
+    it('should not log request headers (may contain Authorization)', () => {
+      captured.requestFulfilled!(
+        makeConfig({ method: 'get', url: '/me', headers: { Authorization: 'Bearer token123' } as any }),
+      );
+      const logCall = vi.mocked(logger.debug).mock.calls[0][0] as Record<string, unknown>;
+      expect(logCall).not.toHaveProperty('headers');
+      expect(JSON.stringify(logCall)).not.toContain('token123');
+    });
+  });
+});

package/template/server/src/libs/http.ts

@@ -0,0 +1,66 @@
+import axios, {
+  type AxiosInstance,
+  type InternalAxiosRequestConfig,
+  type AxiosResponse,
+  isAxiosError,
+} from 'axios';
+import { logger } from '@libs/logger.js';
+import { InternalError } from '@shared/errors/errors.js';
+
+const TIMEOUT_MS = 30_000;
+
+const httpClient: AxiosInstance = axios.create({
+  timeout: TIMEOUT_MS,
+  headers: {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+  },
+});
+
+// Request interceptor — log every outbound call
+httpClient.interceptors.request.use(
+  (config: InternalAxiosRequestConfig): InternalAxiosRequestConfig => {
+    logger.debug(
+      { method: config.method?.toUpperCase(), url: config.url, baseURL: config.baseURL },
+      '[HTTP] Outbound request',
+    );
+    return config;
+  },
+  (error: unknown): never => {
+    logger.error({ err: error }, '[HTTP] Request setup failed');
+    throw new InternalError('Outbound HTTP request could not be constructed');
+  },
+);
+
+// Response interceptor — log responses and convert AxiosError → InternalError
+httpClient.interceptors.response.use(
+  (response: AxiosResponse): AxiosResponse => {
+    logger.debug(
+      {
+        method: response.config.method?.toUpperCase(),
+        url: response.config.url,
+        status: response.status,
+      },
+      '[HTTP] Outbound response',
+    );
+    return response;
+  },
+  (error: unknown): never => {
+    if (isAxiosError(error)) {
+      logger.error(
+        {
+          method: error.config?.method?.toUpperCase(),
+          url: error.config?.url,
+          status: error.response?.status,
+          message: error.message,
+        },
+        '[HTTP] Outbound request failed',
+      );
+    } else {
+      logger.error({ err: error }, '[HTTP] Unexpected outbound error');
+    }
+    throw new InternalError('Outbound HTTP request failed');
+  },
+);
+
+export { httpClient };