spoonfeeder 0.1.0

package/templates/recipes/request-logging/tests/unit/shared/middleware/request-logging.middleware.spec.ts

@@ -0,0 +1,64 @@
+import { RequestLoggingMiddleware } from '../../../../src/shared/middleware/request-logging.middleware';
+import { EventEmitter } from 'node:events';
+
+function createMockRequest(
+  overrides: Partial<{ method: string; url: string; headers: Record<string, string> }> = {},
+) {
+  return {
+    method: overrides.method ?? 'GET',
+    url: overrides.url ?? '/api/test',
+    headers: overrides.headers ?? {},
+  };
+}
+
+function createMockResponse(): EventEmitter & { statusCode: number; getHeader: jest.Mock } {
+  const res = new EventEmitter() as EventEmitter & { statusCode: number; getHeader: jest.Mock };
+  res.statusCode = 200;
+  res.getHeader = jest.fn().mockReturnValue('42');
+  return res;
+}
+
+describe('RequestLoggingMiddleware', () => {
+  let middleware: RequestLoggingMiddleware;
+
+  beforeEach(() => {
+    middleware = new RequestLoggingMiddleware();
+  });
+
+  it('should call next immediately and log on response finish', (done) => {
+    const req = createMockRequest({ method: 'GET', url: '/api/users' });
+    const res = createMockResponse();
+    const logSpy = jest.spyOn((middleware as any).logger, 'log').mockImplementation();
+
+    middleware.use(req as any, res as any, () => {
+      res.statusCode = 200;
+      res.emit('finish');
+
+      expect(logSpy).toHaveBeenCalledTimes(1);
+      const logData = logSpy.mock.calls[0][0];
+      expect(logData).toEqual(
+        expect.objectContaining({ method: 'GET', url: '/api/users', statusCode: 200 }),
+      );
+      done();
+    });
+  });
+
+  it('should use warn for 4xx responses and error for 5xx responses', (done) => {
+    const req = createMockRequest();
+    const res = createMockResponse();
+    const warnSpy = jest.spyOn((middleware as any).logger, 'warn').mockImplementation();
+    const errorSpy = jest.spyOn((middleware as any).logger, 'error').mockImplementation();
+
+    middleware.use(req as any, res as any, () => {
+      res.statusCode = 404;
+      res.emit('finish');
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+
+      res.statusCode = 503;
+      res.emit('finish');
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+
+      done();
+    });
+  });
+});

package/templates/recipes/s3-minio/README.md

@@ -0,0 +1,52 @@
+# S3 / MinIO
+
+Object storage service using the AWS SDK v3, compatible with S3 and MinIO.
+
+## Links
+
+- [AWS SDK for JavaScript v3 Developer Guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/)
+- [@aws-sdk/client-s3 on npm](https://www.npmjs.com/package/@aws-sdk/client-s3)
+- [@aws-sdk/s3-request-presigner on npm](https://www.npmjs.com/package/@aws-sdk/s3-request-presigner)
+- [@aws-sdk/client-s3 on GitHub](https://github.com/aws/aws-sdk-js-v3/tree/main/clients/client-s3)
+
+## Dependencies
+
+| Package                         | Version   | Purpose                                |
+| ------------------------------- | --------- | -------------------------------------- |
+| `@aws-sdk/client-s3`            | `3.750.0` | S3 client for upload, download, delete |
+| `@aws-sdk/s3-request-presigner` | `3.750.0` | Generate presigned URLs                |
+
+## Environment Variables
+
+| Variable               | Description                              | Example                 |
+| ---------------------- | ---------------------------------------- | ----------------------- |
+| `S3_ENDPOINT`          | S3-compatible endpoint URL               | `http://localhost:9000` |
+| `S3_REGION`            | AWS region                               | `eu-west-1`             |
+| `S3_ACCESS_KEY_ID`     | Access key ID                            | `minioadmin`            |
+| `S3_SECRET_ACCESS_KEY` | Secret access key                        | `minioadmin`            |
+| `S3_BUCKET`            | Default bucket name                      | `my-bucket`             |
+| `S3_FORCE_PATH_STYLE`  | Use path-style URLs (required for MinIO) | `true`                  |
+
+## Usage
+
+```typescript
+import { StorageModule } from '@/infrastructure/storage/storage.module';
+
+@Module({
+  imports: [StorageModule],
+})
+export class AppModule {}
+
+// In a service
+constructor(private readonly storage: StorageService) {}
+
+const url = await this.storage.upload('avatars/user-1.png', buffer, 'image/png');
+const presigned = await this.storage.getPresignedUrl('avatars/user-1.png');
+```
+
+## Generated Files
+
+| File                                            | Description                                         |
+| ----------------------------------------------- | --------------------------------------------------- |
+| `src/infrastructure/storage/storage.service.ts` | S3 upload, download, delete, and presign operations |
+| `src/infrastructure/storage/storage.module.ts`  | Storage module with S3 client provider              |

package/templates/recipes/s3-minio/src/infrastructure/storage/storage.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { StorageService } from './storage.service';
+
+@Module({
+  imports: [ConfigModule],
+  providers: [StorageService],
+  exports: [StorageService],
+})
+export class StorageModule {}

package/templates/recipes/s3-minio/src/infrastructure/storage/storage.service.ts

@@ -0,0 +1,72 @@
+import { Injectable } from '@nestjs/common';
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { ConfigService } from '@nestjs/config';
+import { Readable } from 'node:stream';
+
+@Injectable()
+export class StorageService {
+  private readonly client: S3Client;
+  private readonly bucket: string;
+
+  constructor(private readonly config: ConfigService) {
+    this.bucket = this.config.getOrThrow<string>('S3_BUCKET');
+
+    this.client = new S3Client({
+      endpoint: this.config.get<string>('S3_ENDPOINT'),
+      region: this.config.getOrThrow<string>('S3_REGION'),
+      credentials: {
+        accessKeyId: this.config.getOrThrow<string>('S3_ACCESS_KEY_ID'),
+        secretAccessKey: this.config.getOrThrow<string>('S3_SECRET_ACCESS_KEY'),
+      },
+      forcePathStyle: this.config.get<boolean>('S3_FORCE_PATH_STYLE', true),
+    });
+  }
+
+  async upload(key: string, body: Buffer | Readable, contentType: string): Promise<string> {
+    await this.client.send(
+      new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        Body: body,
+        ContentType: contentType,
+      }),
+    );
+
+    return key;
+  }
+
+  async download(key: string): Promise<Readable> {
+    const response = await this.client.send(
+      new GetObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+      }),
+    );
+
+    return response.Body as Readable;
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.send(
+      new DeleteObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+      }),
+    );
+  }
+
+  async getPresignedUrl(key: string, expiresInSeconds = 3600): Promise<string> {
+    const command = new GetObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+    });
+
+    return getSignedUrl(this.client, command, { expiresIn: expiresInSeconds });
+  }
+}

package/templates/recipes/s3-minio/tests/unit/infrastructure/storage/storage.service.spec.ts

@@ -0,0 +1,23 @@
+import { StorageService } from '../../../../src/infrastructure/storage/storage.service';
+
+describe('StorageService', () => {
+  it('should have an upload method', () => {
+    expect(StorageService.prototype.upload).toBeDefined();
+    expect(typeof StorageService.prototype.upload).toBe('function');
+  });
+
+  it('should have a download method', () => {
+    expect(StorageService.prototype.download).toBeDefined();
+    expect(typeof StorageService.prototype.download).toBe('function');
+  });
+
+  it('should have a delete method', () => {
+    expect(StorageService.prototype.delete).toBeDefined();
+    expect(typeof StorageService.prototype.delete).toBe('function');
+  });
+
+  it('should have a getPresignedUrl method', () => {
+    expect(StorageService.prototype.getPresignedUrl).toBeDefined();
+    expect(typeof StorageService.prototype.getPresignedUrl).toBe('function');
+  });
+});

package/templates/recipes/sdk-generation/README.md

@@ -0,0 +1,40 @@
+# SDK Generation
+
+Client SDK generation from OpenAPI specifications using OpenAPI Generator.
+
+## Links
+
+- [OpenAPI Generator](https://openapi-generator.tech)
+- [OpenAPI Generator CLI on npm](https://www.npmjs.com/package/@openapitools/openapi-generator-cli)
+- [OpenAPI Generator on GitHub](https://github.com/OpenAPITools/openapi-generator)
+
+## Dependencies
+
+| Package                               | Version  | Purpose                           |
+| ------------------------------------- | -------- | --------------------------------- |
+| `@openapitools/openapi-generator-cli` | `2.16.3` | CLI wrapper for OpenAPI Generator |
+
+## Usage
+
+Add generation scripts to `package.json`:
+
+```json
+{
+  "scripts": {
+    "sdk:generate": "openapi-generator-cli generate",
+    "sdk:validate": "openapi-generator-cli validate -i openapi.json"
+  }
+}
+```
+
+Run SDK generation:
+
+```bash
+pnpm sdk:generate
+```
+
+## Generated Files
+
+| File                | Description                         |
+| ------------------- | ----------------------------------- |
+| `openapitools.json` | OpenAPI Generator CLI configuration |

package/templates/recipes/sdk-generation/openapitools.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
+  "spaces": 2,
+  "generator-cli": {
+    "version": "7.12.0",
+    "generators": {
+      "typescript-client": {
+        "generatorName": "typescript-axios",
+        "inputSpec": "openapi.json",
+        "output": "generated/typescript-client",
+        "additionalProperties": {
+          "npmName": "@app/api-client",
+          "npmVersion": "1.0.0",
+          "supportsES6": true,
+          "withInterfaces": true,
+          "useSingleRequestParameter": true
+        }
+      }
+    }
+  }
+}

package/templates/recipes/sendgrid/README.md

@@ -0,0 +1,45 @@
+# SendGrid
+
+Transactional email delivery via the SendGrid API.
+
+## Links
+
+- [SendGrid Documentation](https://docs.sendgrid.com/)
+- [SendGrid Node.js Quickstart](https://docs.sendgrid.com/for-developers/sending-email/quickstart-nodejs)
+- [@sendgrid/mail on npm](https://www.npmjs.com/package/@sendgrid/mail)
+- [@sendgrid/mail on GitHub](https://github.com/sendgrid/sendgrid-nodejs)
+
+## Dependencies
+
+| Package          | Version | Purpose                  |
+| ---------------- | ------- | ------------------------ |
+| `@sendgrid/mail` | `8.1.4` | SendGrid Mail API client |
+
+## Environment Variables
+
+| Variable              | Description             | Example               |
+| --------------------- | ----------------------- | --------------------- |
+| `SENDGRID_API_KEY`    | SendGrid API key        | `SG.xxxxxx`           |
+| `SENDGRID_FROM_EMAIL` | Verified sender address | `noreply@example.com` |
+| `SENDGRID_FROM_NAME`  | Sender display name     | `My App`              |
+
+## Usage
+
+```typescript
+import { SendGridService } from '@/infrastructure/notifications/sendgrid.service';
+
+constructor(private readonly sendgrid: SendGridService) {}
+
+await this.sendgrid.send({
+  to: 'user@example.com',
+  subject: 'Welcome',
+  text: 'Hello!',
+  html: '<h1>Hello!</h1>',
+});
+```
+
+## Generated Files
+
+| File                                                   | Description            |
+| ------------------------------------------------------ | ---------------------- |
+| `src/infrastructure/notifications/sendgrid.service.ts` | SendGrid email service |

package/templates/recipes/sendgrid/src/infrastructure/notifications/sendgrid.service.ts

@@ -0,0 +1,60 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import * as sgMail from '@sendgrid/mail';
+
+interface SendEmailOptions {
+  to: string | string[];
+  subject: string;
+  text?: string;
+  html?: string;
+  templateId?: string;
+  dynamicTemplateData?: Record<string, unknown>;
+}
+
+@Injectable()
+export class SendGridService implements OnModuleInit {
+  private readonly logger = new Logger(SendGridService.name);
+  private fromEmail: string;
+  private fromName: string;
+
+  constructor(private readonly config: ConfigService) {}
+
+  onModuleInit(): void {
+    const apiKey = this.config.getOrThrow<string>('SENDGRID_API_KEY');
+    this.fromEmail = this.config.getOrThrow<string>('SENDGRID_FROM_EMAIL');
+    this.fromName = this.config.get<string>('SENDGRID_FROM_NAME', 'App');
+
+    sgMail.setApiKey(apiKey);
+  }
+
+  async send(options: SendEmailOptions): Promise<void> {
+    const message: sgMail.MailDataRequired = {
+      to: options.to,
+      from: { email: this.fromEmail, name: this.fromName },
+      subject: options.subject,
+      ...(options.text && { text: options.text }),
+      ...(options.html && { html: options.html }),
+      ...(options.templateId && { templateId: options.templateId }),
+      ...(options.dynamicTemplateData && {
+        dynamicTemplateData: options.dynamicTemplateData,
+      }),
+    };
+
+    try {
+      await sgMail.send(message);
+      this.logger.log(
+        `Email sent to ${Array.isArray(options.to) ? options.to.join(', ') : options.to}`,
+      );
+    } catch (error) {
+      this.logger.error(
+        `Failed to send email: ${(error as Error).message}`,
+        (error as Error).stack,
+      );
+      throw error;
+    }
+  }
+
+  async sendMultiple(messages: SendEmailOptions[]): Promise<void> {
+    await Promise.all(messages.map((msg) => this.send(msg)));
+  }
+}

package/templates/recipes/sendgrid/tests/unit/infrastructure/notifications/sendgrid.service.spec.ts

@@ -0,0 +1,59 @@
+import { ConfigService } from '@nestjs/config';
+import { SendGridService } from '../../../../src/infrastructure/notifications/sendgrid.service';
+
+jest.mock('@sendgrid/mail', () => ({
+  setApiKey: jest.fn(),
+  send: jest.fn().mockResolvedValue([{ statusCode: 202, body: {} }]),
+}));
+
+describe('SendGridService', () => {
+  let service: SendGridService;
+  let sgMail: { setApiKey: jest.Mock; send: jest.Mock };
+
+  beforeEach(() => {
+    const configService = new ConfigService({
+      SENDGRID_API_KEY: 'SG.test-key',
+      SENDGRID_FROM_EMAIL: 'sender@example.com',
+      SENDGRID_FROM_NAME: 'TestApp',
+    });
+
+    service = new SendGridService(configService);
+    service.onModuleInit();
+
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    sgMail = require('@sendgrid/mail');
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should set the API key on init', () => {
+    expect(sgMail.setApiKey).toHaveBeenCalledWith('SG.test-key');
+  });
+
+  it('should send an email with the correct message shape', async () => {
+    await service.send({
+      to: 'recipient@example.com',
+      subject: 'Hello',
+      text: 'World',
+    });
+
+    expect(sgMail.send).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: 'recipient@example.com',
+        subject: 'Hello',
+        text: 'World',
+        from: { email: 'sender@example.com', name: 'TestApp' },
+      }),
+    );
+  });
+
+  it('should propagate errors from the SendGrid client', async () => {
+    sgMail.send.mockRejectedValueOnce(new Error('Unauthorized'));
+
+    await expect(service.send({ to: 'a@b.com', subject: 'fail', text: 'body' })).rejects.toThrow(
+      'Unauthorized',
+    );
+  });
+});

package/templates/recipes/sentry/README.md

@@ -0,0 +1,49 @@
+# Sentry
+
+Error tracking and performance monitoring for NestJS with the official Sentry SDK.
+
+## Links
+
+- [Sentry NestJS Guide](https://docs.sentry.io/platforms/javascript/guides/nestjs/)
+- [@sentry/nestjs on npm](https://www.npmjs.com/package/@sentry/nestjs)
+- [@sentry/nestjs on GitHub](https://github.com/getsentry/sentry-javascript)
+
+## Dependencies
+
+| Package          | Version  | Purpose                           |
+| ---------------- | -------- | --------------------------------- |
+| `@sentry/nestjs` | `8.48.0` | Sentry SDK for NestJS integration |
+
+## Environment Variables
+
+| Variable                    | Description                         | Example                                          |
+| --------------------------- | ----------------------------------- | ------------------------------------------------ |
+| `SENTRY_DSN`                | Sentry project DSN                  | `https://examplePublicKey@o0.ingest.sentry.io/0` |
+| `SENTRY_ENVIRONMENT`        | Deployment environment name         | `production`                                     |
+| `SENTRY_TRACES_SAMPLE_RATE` | Performance sampling rate (0.0–1.0) | `0.2`                                            |
+
+## Usage
+
+```typescript
+import { SentryModule } from '@/infrastructure/sentry/sentry.module';
+
+@Module({
+  imports: [SentryModule],
+})
+export class AppModule {}
+```
+
+Register the global exception filter in `main.ts`:
+
+```typescript
+import { SentryExceptionFilter } from '@/infrastructure/sentry/sentry.filter';
+
+app.useGlobalFilters(new SentryExceptionFilter());
+```
+
+## Generated Files
+
+| File                                         | Description                                    |
+| -------------------------------------------- | ---------------------------------------------- |
+| `src/infrastructure/sentry/sentry.module.ts` | Sentry module with SDK initialisation          |
+| `src/infrastructure/sentry/sentry.filter.ts` | Global exception filter that reports to Sentry |

package/templates/recipes/sentry/src/infrastructure/sentry/sentry.filter.ts

@@ -0,0 +1,34 @@
+import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus } from '@nestjs/common';
+import * as Sentry from '@sentry/nestjs';
+import { FastifyReply, FastifyRequest } from 'fastify';
+
+@Catch()
+export class SentryExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const reply = ctx.getResponse<FastifyReply>();
+    const request = ctx.getRequest<FastifyRequest>();
+
+    const status =
+      exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    if (status >= HttpStatus.INTERNAL_SERVER_ERROR) {
+      Sentry.withScope((scope) => {
+        scope.setExtra('url', request.url);
+        scope.setExtra('method', request.method);
+        scope.setExtra('headers', request.headers);
+        Sentry.captureException(exception);
+      });
+    }
+
+    const message =
+      exception instanceof HttpException ? exception.getResponse() : 'Internal server error';
+
+    reply.status(status).send({
+      statusCode: status,
+      message,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+    });
+  }
+}

package/templates/recipes/sentry/src/infrastructure/sentry/sentry.module.ts

@@ -0,0 +1,23 @@
+import { Module, OnApplicationBootstrap } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import * as Sentry from '@sentry/nestjs';
+
+@Module({})
+export class SentryModule implements OnApplicationBootstrap {
+  constructor(private readonly config: ConfigService) {}
+
+  onApplicationBootstrap(): void {
+    const dsn = this.config.get<string>('SENTRY_DSN');
+
+    if (!dsn) {
+      return;
+    }
+
+    Sentry.init({
+      dsn,
+      environment: this.config.get<string>('SENTRY_ENVIRONMENT', 'development'),
+      tracesSampleRate: this.config.get<number>('SENTRY_TRACES_SAMPLE_RATE', 0.2),
+      integrations: [Sentry.nestIntegration()],
+    });
+  }
+}

package/templates/recipes/sentry/tests/unit/infrastructure/sentry/sentry.filter.spec.ts

@@ -0,0 +1,50 @@
+import { ArgumentsHost, HttpException, HttpStatus } from '@nestjs/common';
+import { SentryExceptionFilter } from '../../../../src/infrastructure/sentry/sentry.filter';
+
+jest.mock('@sentry/nestjs', () => ({
+  withScope: jest.fn(),
+  captureException: jest.fn(),
+}));
+
+describe('SentryExceptionFilter', () => {
+  let filter: SentryExceptionFilter;
+  let mockSend: jest.Mock;
+  let mockStatus: jest.Mock;
+
+  const createMockHost = (): ArgumentsHost => {
+    mockSend = jest.fn();
+    mockStatus = jest.fn().mockReturnValue({ send: mockSend });
+
+    return {
+      switchToHttp: () => ({
+        getResponse: () => ({ status: mockStatus }),
+        getRequest: () => ({ url: '/test', method: 'GET', headers: {} }),
+      }),
+    } as unknown as ArgumentsHost;
+  };
+
+  beforeEach(() => {
+    filter = new SentryExceptionFilter();
+  });
+
+  it('should be defined', () => {
+    expect(filter).toBeDefined();
+  });
+
+  it('should use the status from HttpException', () => {
+    const host = createMockHost();
+    const exception = new HttpException('Not Found', HttpStatus.NOT_FOUND);
+
+    filter.catch(exception, host);
+
+    expect(mockStatus).toHaveBeenCalledWith(HttpStatus.NOT_FOUND);
+  });
+
+  it('should default to 500 for non-HttpException errors', () => {
+    const host = createMockHost();
+
+    filter.catch(new Error('unexpected'), host);
+
+    expect(mockStatus).toHaveBeenCalledWith(HttpStatus.INTERNAL_SERVER_ERROR);
+  });
+});

package/templates/recipes/seq2/README.md

@@ -0,0 +1,41 @@
+# Seq
+
+Structured log shipping to Seq via the seq-logging transport.
+
+## Links
+
+- [Seq Overview](https://docs.datalust.co/docs/an-overview-of-seq)
+- [seq-logging on npm](https://www.npmjs.com/package/seq-logging)
+- [seq-logging on GitHub](https://github.com/datalust/seq-logging)
+
+## Dependencies
+
+| Package       | Version | Purpose                                 |
+| ------------- | ------- | --------------------------------------- |
+| `seq-logging` | `2.0.1` | HTTP transport for shipping logs to Seq |
+
+## Environment Variables
+
+| Variable         | Description                    | Example                 |
+| ---------------- | ------------------------------ | ----------------------- |
+| `SEQ_SERVER_URL` | Seq server ingestion endpoint  | `http://localhost:5341` |
+| `SEQ_API_KEY`    | Seq API key for authentication | `abcdef1234567890`      |
+
+## Usage
+
+```typescript
+import { SeqTransport } from '@/infrastructure/logging/seq.transport';
+
+const seq = new SeqTransport({
+  serverUrl: 'http://localhost:5341',
+  apiKey: 'your-api-key',
+});
+
+seq.log('Information', 'User {UserId} logged in', { UserId: 42 });
+```
+
+## Generated Files
+
+| File                                          | Description                            |
+| --------------------------------------------- | -------------------------------------- |
+| `src/infrastructure/logging/seq.transport.ts` | Seq log transport wrapping seq-logging |