@dismissible/nestjs-api 0.0.2-canary.5daf195.0

package/src/swagger/swagger.config.spec.ts

@@ -0,0 +1,113 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { SwaggerConfig } from './swagger.config';
+
+describe('SwaggerConfig', () => {
+  describe('enabled', () => {
+    it('should transform string "true" to boolean true', () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: 'true' });
+      expect(config.enabled).toBe(true);
+    });
+
+    it('should transform string "false" to boolean false', () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: 'false' });
+      expect(config.enabled).toBe(false);
+    });
+
+    it('should keep boolean true as true', () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: true });
+      expect(config.enabled).toBe(true);
+    });
+
+    it('should keep boolean false as false', () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: false });
+      expect(config.enabled).toBe(false);
+    });
+
+    it('should transform other string values to false', () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: 'yes' });
+      expect(config.enabled).toBe(false);
+    });
+
+    it('should handle case-insensitive "true"', () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: 'TRUE' });
+      expect(config.enabled).toBe(true);
+    });
+
+    it('should handle case-insensitive "True"', () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: 'True' });
+      expect(config.enabled).toBe(true);
+    });
+  });
+
+  describe('path', () => {
+    it('should accept string path', () => {
+      const config = plainToInstance(SwaggerConfig, {
+        enabled: true,
+        path: 'api-docs',
+      });
+      expect(config.path).toBe('api-docs');
+    });
+
+    it('should allow path to be optional', () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: true });
+      expect(config.path).toBeUndefined();
+    });
+  });
+
+  describe('validation', () => {
+    it('should pass validation with valid config', async () => {
+      const config = plainToInstance(SwaggerConfig, {
+        enabled: true,
+        path: 'docs',
+      });
+      const errors = await validate(config);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass validation with only required fields', async () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: true });
+      const errors = await validate(config);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should pass validation when enabled is transformed from string', async () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: 'true' });
+      const errors = await validate(config);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should fail validation when enabled is missing', async () => {
+      const config = plainToInstance(SwaggerConfig, {});
+      const errors = await validate(config);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors[0].property).toBe('enabled');
+    });
+
+    it('should fail validation when enabled is null', async () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: null });
+      const errors = await validate(config);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors[0].property).toBe('enabled');
+    });
+
+    it('should fail validation when enabled is undefined', async () => {
+      const config = plainToInstance(SwaggerConfig, { enabled: undefined });
+      const errors = await validate(config);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors[0].property).toBe('enabled');
+    });
+
+    it('should fail validation when path is not a string', async () => {
+      const config = plainToInstance(SwaggerConfig, {
+        enabled: true,
+        path: 123,
+      });
+      const errors = await validate(config);
+      expect(errors.length).toBeGreaterThan(0);
+      const pathError = errors.find((e) => e.property === 'path');
+      expect(pathError).toBeDefined();
+    });
+  });
+});

package/src/swagger/swagger.config.ts

@@ -0,0 +1,12 @@
+import { IsBoolean, IsOptional, IsString } from 'class-validator';
+import { TransformBoolean } from '@dismissible/nestjs-validation';
+
+export class SwaggerConfig {
+  @IsBoolean()
+  @TransformBoolean()
+  public readonly enabled!: boolean;
+
+  @IsString()
+  @IsOptional()
+  public readonly path?: string;
+}

package/src/swagger/swagger.factory.spec.ts

@@ -0,0 +1,125 @@
+import { INestApplication } from '@nestjs/common';
+import { DocumentBuilder } from '@nestjs/swagger';
+import { configureAppWithSwagger } from './swagger.factory';
+import { SwaggerConfig } from './swagger.config';
+
+const mockCreateDocument = jest.fn();
+const mockSetup = jest.fn();
+const mockSetTitle = jest.fn().mockReturnThis();
+const mockSetDescription = jest.fn().mockReturnThis();
+const mockSetVersion = jest.fn().mockReturnThis();
+const mockBuild = jest.fn().mockReturnValue({});
+
+jest.mock('@nestjs/swagger', () => ({
+  SwaggerModule: {
+    createDocument: (...args: any[]) => mockCreateDocument(...args),
+    setup: (...args: any[]) => mockSetup(...args),
+  },
+  DocumentBuilder: jest.fn().mockImplementation(() => ({
+    setTitle: mockSetTitle,
+    setDescription: mockSetDescription,
+    setVersion: mockSetVersion,
+    build: mockBuild,
+  })),
+}));
+
+describe('configureAppWithSwagger', () => {
+  let mockApp: jest.Mocked<INestApplication>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockApp = {} as any;
+  });
+
+  it('should configure Swagger when enabled is true', () => {
+    const swaggerConfig: SwaggerConfig = {
+      enabled: true,
+      path: 'docs',
+    };
+
+    configureAppWithSwagger(mockApp, swaggerConfig);
+
+    expect(DocumentBuilder).toHaveBeenCalled();
+    expect(mockSetTitle).toHaveBeenCalledWith('Dismissible');
+    expect(mockSetDescription).toHaveBeenCalledWith('An API to handle dismissible items for users');
+    expect(mockSetVersion).toHaveBeenCalledWith('1.0');
+    expect(mockBuild).toHaveBeenCalled();
+    expect(mockSetup).toHaveBeenCalledWith('docs', mockApp, expect.any(Function), {
+      useGlobalPrefix: true,
+    });
+  });
+
+  it('should use default path "docs" when path is not provided', () => {
+    const swaggerConfig: SwaggerConfig = {
+      enabled: true,
+    };
+
+    configureAppWithSwagger(mockApp, swaggerConfig);
+
+    expect(mockSetup).toHaveBeenCalledWith('docs', mockApp, expect.any(Function), {
+      useGlobalPrefix: true,
+    });
+  });
+
+  it('should use custom path when provided', () => {
+    const swaggerConfig: SwaggerConfig = {
+      enabled: true,
+      path: 'api-docs',
+    };
+
+    configureAppWithSwagger(mockApp, swaggerConfig);
+
+    expect(mockSetup).toHaveBeenCalledWith('api-docs', mockApp, expect.any(Function), {
+      useGlobalPrefix: true,
+    });
+  });
+
+  it('should not configure Swagger when enabled is false', () => {
+    const swaggerConfig: SwaggerConfig = {
+      enabled: false,
+    };
+
+    configureAppWithSwagger(mockApp, swaggerConfig);
+
+    expect(DocumentBuilder).not.toHaveBeenCalled();
+    expect(mockSetup).not.toHaveBeenCalled();
+  });
+
+  it('should create document with correct operationIdFactory', () => {
+    const swaggerConfig: SwaggerConfig = {
+      enabled: true,
+    };
+
+    configureAppWithSwagger(mockApp, swaggerConfig);
+
+    const setupCall = mockSetup.mock.calls[0];
+    const documentFactory = setupCall[2];
+    documentFactory();
+
+    expect(mockCreateDocument).toHaveBeenCalledWith(
+      mockApp,
+      {},
+      expect.objectContaining({
+        operationIdFactory: expect.any(Function),
+      }),
+    );
+  });
+
+  it('should use methodKey as operationId', () => {
+    const swaggerConfig: SwaggerConfig = {
+      enabled: true,
+    };
+
+    configureAppWithSwagger(mockApp, swaggerConfig);
+
+    const setupCall = mockSetup.mock.calls[0];
+    const documentFactory = setupCall[2];
+    documentFactory();
+
+    const createDocumentCall = mockCreateDocument.mock.calls[0];
+    const operationIdFactory = createDocumentCall[2].operationIdFactory;
+
+    expect(operationIdFactory('UserController', 'createUser')).toBe('createUser');
+    expect(operationIdFactory('ItemController', 'getItem')).toBe('getItem');
+  });
+});

package/src/swagger/swagger.factory.ts

@@ -0,0 +1,24 @@
+import { INestApplication } from '@nestjs/common';
+import { DocumentBuilder, SwaggerDocumentOptions, SwaggerModule } from '@nestjs/swagger';
+import { SwaggerConfig } from './swagger.config';
+
+const swaggerDocumentOptions: SwaggerDocumentOptions = {
+  operationIdFactory: (_controllerKey: string, methodKey: string) => methodKey,
+};
+
+export function configureAppWithSwagger(app: INestApplication, swaggerConfig: SwaggerConfig) {
+  if (swaggerConfig.enabled) {
+    const { path = 'docs' } = swaggerConfig;
+
+    const config = new DocumentBuilder()
+      .setTitle('Dismissible')
+      .setDescription('An API to handle dismissible items for users')
+      .setVersion('1.0')
+      .build();
+
+    const documentFactory = () => SwaggerModule.createDocument(app, config, swaggerDocumentOptions);
+    SwaggerModule.setup(path, app, documentFactory, {
+      useGlobalPrefix: true,
+    });
+  }
+}

package/src/validation/index.ts

@@ -0,0 +1 @@
+export * from './validation.config';

package/src/validation/validation.config.ts

@@ -0,0 +1,47 @@
+import { IsBoolean, IsOptional } from 'class-validator';
+import { TransformBoolean } from '@dismissible/nestjs-validation';
+
+/**
+ * Configuration for NestJS ValidationPipe
+ * @see https://docs.nestjs.com/techniques/validation
+ */
+export class ValidationConfig {
+  /**
+   * Whether to disable error messages in validation responses.
+   * Should be true in production to prevent information disclosure.
+   * @default true in production, false in development
+   */
+  @IsBoolean()
+  @IsOptional()
+  @TransformBoolean()
+  public readonly disableErrorMessages?: boolean;
+
+  /**
+   * If set to true, validator will strip validated (returned) object of any properties
+   * that do not use any validation decorators.
+   * @default true
+   */
+  @IsBoolean()
+  @IsOptional()
+  @TransformBoolean()
+  public readonly whitelist?: boolean;
+
+  /**
+   * If set to true, instead of stripping non-whitelisted properties,
+   * validator will throw an error.
+   * @default true
+   */
+  @IsBoolean()
+  @IsOptional()
+  @TransformBoolean()
+  public readonly forbidNonWhitelisted?: boolean;
+
+  /**
+   * If set to true, class-transformer will attempt transformation based on TS reflected type.
+   * @default true
+   */
+  @IsBoolean()
+  @IsOptional()
+  @TransformBoolean()
+  public readonly transform?: boolean;
+}

package/test/config/.env.yaml

@@ -0,0 +1,23 @@
+server:
+  port: 3001
+
+cors:
+  enabled: false
+
+helmet:
+  enabled: false
+
+swagger:
+  enabled: false
+
+db:
+  connectionString: ${DATABASE_URL:-postgresql://postgres:postgres@localhost:5432/dismissible}
+
+jwtAuth:
+  enabled: false
+
+validation:
+  disableErrorMessages: false
+  whitelist: true
+  forbidNonWhitelisted: true
+  transform: true

package/test/config-jwt-auth/.env.yaml

@@ -0,0 +1,26 @@
+server:
+  port: 3001
+
+cors:
+  enabled: false
+
+helmet:
+  enabled: false
+
+swagger:
+  enabled: false
+
+db:
+  connectionString: ${DATABASE_URL:-postgresql://postgres:postgres@localhost:5432/dismissible}
+
+jwtAuth:
+  enabled: true
+  wellKnownUrl: https://auth.example.com/.well-known/openid-configuration
+  issuer: https://auth.example.com
+  audience: dismissible-api
+
+validation:
+  disableErrorMessages: false
+  whitelist: true
+  forbidNonWhitelisted: true
+  transform: true

package/test/dismiss.e2e-spec.ts

@@ -0,0 +1,61 @@
+import { INestApplication } from '@nestjs/common';
+import request from 'supertest';
+import { join } from 'path';
+import { createTestApp, cleanupTestData } from '../src/app-test.factory';
+import { NullLogger } from '@dismissible/nestjs-logger';
+
+describe('DELETE /v1/users/:userId/items/:id (dismiss)', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    app = await createTestApp({
+      moduleOptions: {
+        configPath: join(__dirname, 'config'),
+        logger: NullLogger,
+      },
+    });
+    await cleanupTestData(app);
+  });
+
+  afterAll(async () => {
+    await cleanupTestData(app);
+    await app.close();
+  });
+
+  it('should dismiss an existing item', async () => {
+    const userId = 'user-dismiss-1';
+    await request(app.getHttpServer()).get(`/v1/users/${userId}/items/dismiss-test-1`).expect(200);
+
+    const response = await request(app.getHttpServer())
+      .delete(`/v1/users/${userId}/items/dismiss-test-1`)
+      .expect(200);
+
+    expect(response.body.data).toBeDefined();
+    expect(response.body.data.dismissedAt).toBeDefined();
+  });
+
+  it('should return 400 when dismissing non-existent item', async () => {
+    const response = await request(app.getHttpServer())
+      .delete('/v1/users/user-123/items/non-existent-item')
+      .expect(400);
+
+    expect(response.body.error).toBeDefined();
+    expect(response.body.error.message).toContain('not found');
+  });
+
+  it('should return 400 when dismissing already dismissed item', async () => {
+    const userId = 'user-dismiss-2';
+    await request(app.getHttpServer()).get(`/v1/users/${userId}/items/dismiss-test-2`).expect(200);
+
+    await request(app.getHttpServer())
+      .delete(`/v1/users/${userId}/items/dismiss-test-2`)
+      .expect(200);
+
+    const response = await request(app.getHttpServer())
+      .delete(`/v1/users/${userId}/items/dismiss-test-2`)
+      .expect(400);
+
+    expect(response.body.error).toBeDefined();
+    expect(response.body.error.message).toContain('already dismissed');
+  });
+});

package/test/full-cycle.e2e-spec.ts

@@ -0,0 +1,55 @@
+import { INestApplication } from '@nestjs/common';
+import request from 'supertest';
+import { join } from 'path';
+import { createTestApp, cleanupTestData } from '../src/app-test.factory';
+import { NullLogger } from '@dismissible/nestjs-logger';
+
+describe('Full lifecycle flow', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    app = await createTestApp({
+      moduleOptions: {
+        configPath: join(__dirname, 'config'),
+        logger: NullLogger,
+      },
+    });
+    await cleanupTestData(app);
+  });
+
+  afterAll(async () => {
+    if (app) {
+      await cleanupTestData(app);
+      await app.close();
+    }
+  });
+
+  it('should handle create -> dismiss -> restore -> dismiss cycle', async () => {
+    const userId = 'lifecycle-user';
+    const itemId = 'lifecycle-test';
+
+    const createResponse = await request(app.getHttpServer())
+      .get(`/v1/users/${userId}/items/${itemId}`)
+      .expect(200);
+
+    expect(createResponse.body.data.dismissedAt).toBeUndefined();
+
+    const dismissResponse = await request(app.getHttpServer())
+      .delete(`/v1/users/${userId}/items/${itemId}`)
+      .expect(200);
+
+    expect(dismissResponse.body.data.dismissedAt).toBeDefined();
+
+    const restoreResponse = await request(app.getHttpServer())
+      .post(`/v1/users/${userId}/items/${itemId}`)
+      .expect(201);
+
+    expect(restoreResponse.body.data.dismissedAt).toBeUndefined();
+
+    const dismissAgainResponse = await request(app.getHttpServer())
+      .delete(`/v1/users/${userId}/items/${itemId}`)
+      .expect(200);
+
+    expect(dismissAgainResponse.body.data.dismissedAt).toBeDefined();
+  });
+});

package/test/get-or-create.e2e-spec.ts

@@ -0,0 +1,51 @@
+import { INestApplication } from '@nestjs/common';
+import request from 'supertest';
+import { join } from 'path';
+import { createTestApp, cleanupTestData } from '../src/app-test.factory';
+import { NullLogger } from '@dismissible/nestjs-logger';
+
+describe('GET /v1/users/:userId/items/:id (get-or-create)', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    app = await createTestApp({
+      moduleOptions: {
+        configPath: join(__dirname, 'config'),
+        logger: NullLogger,
+      },
+    });
+    await cleanupTestData(app);
+  });
+
+  afterAll(async () => {
+    await cleanupTestData(app);
+    await app.close();
+  });
+
+  it('should create a new item on first request', async () => {
+    const response = await request(app.getHttpServer())
+      .get('/v1/users/user-123/items/test-banner-1')
+      .expect(200);
+
+    expect(response.body.data).toBeDefined();
+    expect(response.body.data.itemId).toBe('test-banner-1');
+    expect(response.body.data.userId).toBe('user-123');
+    expect(response.body.data.createdAt).toBeDefined();
+    expect(response.body.data.dismissedAt).toBeUndefined();
+  });
+
+  it('should return existing item on subsequent requests', async () => {
+    const firstResponse = await request(app.getHttpServer())
+      .get('/v1/users/user-456/items/test-banner-2')
+      .expect(200);
+
+    const createdAt = firstResponse.body.data.createdAt;
+
+    const secondResponse = await request(app.getHttpServer())
+      .get('/v1/users/user-456/items/test-banner-2')
+      .expect(200);
+
+    expect(secondResponse.body.data.itemId).toBe('test-banner-2');
+    expect(secondResponse.body.data.createdAt).toBe(createdAt);
+  });
+});