spoonfeeder 0.1.0

package/templates/recipes/mongoose/README.md

@@ -0,0 +1,42 @@
+# Mongoose
+
+MongoDB integration using Mongoose ODM for NestJS applications.
+
+## Links
+
+- [NestJS MongoDB Documentation](https://docs.nestjs.com/techniques/mongodb)
+- [Mongoose Documentation](https://mongoosejs.com)
+- [@nestjs/mongoose on npm](https://www.npmjs.com/package/@nestjs/mongoose)
+- [Mongoose on npm](https://www.npmjs.com/package/mongoose)
+- [Mongoose on GitHub](https://github.com/Automattic/mongoose)
+
+## Dependencies
+
+| Package            | Version  | Purpose                             |
+| ------------------ | -------- | ----------------------------------- |
+| `@nestjs/mongoose` | `10.1.0` | NestJS Mongoose integration module  |
+| `mongoose`         | `8.9.5`  | MongoDB object modeling for Node.js |
+
+## Environment Variables
+
+| Variable        | Default                     | Description            |
+| --------------- | --------------------------- | ---------------------- |
+| `MONGO_URI`     | `mongodb://localhost:27017` | MongoDB connection URI |
+| `MONGO_DB_NAME` | —                           | Database name          |
+
+## Usage
+
+```typescript
+import { DatabaseModule } from '@/infrastructure/database/database.module';
+
+@Module({
+  imports: [DatabaseModule],
+})
+export class AppModule {}
+```
+
+## Generated Files
+
+| File                                             | Description                                             |
+| ------------------------------------------------ | ------------------------------------------------------- |
+| `src/infrastructure/database/database.module.ts` | MongooseModule configured with async connection factory |

package/templates/recipes/mongoose/src/infrastructure/database/database.module.ts.ejs

@@ -0,0 +1,17 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { MongooseModule } from '@nestjs/mongoose';
+
+@Module({
+  imports: [
+    MongooseModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService) => ({
+        uri: configService.get<string>('MONGO_URI', 'mongodb://localhost:27017'),
+        dbName: configService.get<string>('MONGO_DB_NAME', '<%= name %>'),
+      }),
+    }),
+  ],
+})
+export class DatabaseModule {}

package/templates/recipes/mongoose/tests/unit/infrastructure/database/database.module.spec.ts

@@ -0,0 +1,25 @@
+import { ConfigService } from '@nestjs/config';
+
+describe('Mongoose DatabaseModule config', () => {
+  it('should use MONGO_URI from config with a default fallback', () => {
+    const configService = new ConfigService({});
+    const uri = configService.get<string>('MONGO_URI', 'mongodb://localhost:27017');
+    expect(uri).toBe('mongodb://localhost:27017');
+  });
+
+  it('should use the configured MONGO_URI when present', () => {
+    const configService = new ConfigService({
+      MONGO_URI: 'mongodb://mongo.prod:27017',
+    });
+    const uri = configService.get<string>('MONGO_URI', 'mongodb://localhost:27017');
+    expect(uri).toBe('mongodb://mongo.prod:27017');
+  });
+
+  it('should use MONGO_DB_NAME from config', () => {
+    const configService = new ConfigService({
+      MONGO_DB_NAME: 'my-app',
+    });
+    const dbName = configService.get<string>('MONGO_DB_NAME', 'default-db');
+    expect(dbName).toBe('my-app');
+  });
+});

package/templates/recipes/multi-tenancy/README.md

@@ -0,0 +1,49 @@
+# Multi-Tenancy
+
+Request-scoped tenant context using AsyncLocalStorage with middleware and decorator.
+
+## Links
+
+- [Node.js AsyncLocalStorage](https://nodejs.org/api/async_context.html#class-asynclocalstorage)
+- [NestJS Middleware](https://docs.nestjs.com/middleware)
+- [NestJS Custom Decorators](https://docs.nestjs.com/custom-decorators)
+
+## Dependencies
+
+No additional dependencies required. Uses the built-in `node:async_hooks` module.
+
+| Package | Version | Purpose                     |
+| ------- | ------- | --------------------------- |
+| (none)  | -       | Built-in `node:async_hooks` |
+
+## Usage
+
+Register middleware in your module:
+
+```typescript
+import { TenantMiddleware } from '@/shared/middleware/tenant.middleware';
+
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(TenantMiddleware).forRoutes('*');
+  }
+}
+```
+
+Access the tenant in controllers:
+
+```typescript
+import { CurrentTenant } from '@/shared/decorators/tenant.decorator';
+
+@Get('data')
+getData(@CurrentTenant() tenantId: string) {
+  return this.service.findByTenant(tenantId);
+}
+```
+
+## Generated Files
+
+| File                                         | Description                                     |
+| -------------------------------------------- | ----------------------------------------------- |
+| `src/shared/middleware/tenant.middleware.ts` | Tenant context middleware via AsyncLocalStorage |
+| `src/shared/decorators/tenant.decorator.ts`  | `@CurrentTenant()` parameter decorator          |

package/templates/recipes/multi-tenancy/src/shared/decorators/tenant.decorator.ts

@@ -0,0 +1,14 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+import { tenantStorage } from '@/shared/middleware/tenant.middleware';
+
+export const CurrentTenant = createParamDecorator(
+  (_data: unknown, _ctx: ExecutionContext): string => {
+    const context = tenantStorage.getStore();
+
+    if (!context) {
+      throw new Error('Tenant context not available — is TenantMiddleware registered?');
+    }
+
+    return context.tenantId;
+  },
+);

package/templates/recipes/multi-tenancy/src/shared/middleware/tenant.middleware.ts

@@ -0,0 +1,49 @@
+import { Injectable, NestMiddleware, UnauthorizedException } from '@nestjs/common';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { FastifyReply, FastifyRequest } from 'fastify';
+
+export interface TenantContext {
+  tenantId: string;
+}
+
+export const tenantStorage = new AsyncLocalStorage<TenantContext>();
+
+const TENANT_HEADER = 'x-tenant-id';
+
+@Injectable()
+export class TenantMiddleware implements NestMiddleware {
+  use(req: FastifyRequest['raw'], res: FastifyReply['raw'], next: () => void): void {
+    const tenantId = req.headers[TENANT_HEADER] as string | undefined;
+
+    if (!tenantId) {
+      throw new UnauthorizedException(`Missing required header: ${TENANT_HEADER}`);
+    }
+
+    const context: TenantContext = { tenantId };
+
+    tenantStorage.run(context, () => {
+      next();
+    });
+  }
+}
+
+/**
+ * Retrieve the current tenant context from anywhere in the async call chain.
+ * Returns undefined if called outside of a request context.
+ */
+export function getTenantContext(): TenantContext | undefined {
+  return tenantStorage.getStore();
+}
+
+/**
+ * Retrieve the current tenant ID or throw if not in a request context.
+ */
+export function requireTenantId(): string {
+  const context = tenantStorage.getStore();
+
+  if (!context) {
+    throw new Error('Tenant context not available outside of a request');
+  }
+
+  return context.tenantId;
+}

package/templates/recipes/multi-tenancy/tests/unit/shared/middleware/tenant.middleware.spec.ts

@@ -0,0 +1,29 @@
+import { UnauthorizedException } from '@nestjs/common';
+import { TenantMiddleware, getTenantContext } from '@/shared/middleware/tenant.middleware';
+
+describe('TenantMiddleware', () => {
+  let middleware: TenantMiddleware;
+
+  beforeEach(() => {
+    middleware = new TenantMiddleware();
+  });
+
+  it('should set tenant context when x-tenant-id header is present', (done) => {
+    const req = { headers: { 'x-tenant-id': 'tenant-abc' } } as any;
+    const res = {} as any;
+
+    middleware.use(req, res, () => {
+      const context = getTenantContext();
+      expect(context).toBeDefined();
+      expect(context!.tenantId).toBe('tenant-abc');
+      done();
+    });
+  });
+
+  it('should throw UnauthorizedException when x-tenant-id header is missing', () => {
+    const req = { headers: {} } as any;
+    const res = {} as any;
+
+    expect(() => middleware.use(req, res, jest.fn())).toThrow(UnauthorizedException);
+  });
+});

package/templates/recipes/nodemailer/README.md

@@ -0,0 +1,55 @@
+# Nodemailer
+
+Email sending via @nestjs-modules/mailer with Nodemailer transport.
+
+## Links
+
+- [NestJS Mailer Module](https://nest-modules.github.io/mailer/)
+- [Nodemailer Documentation](https://nodemailer.com)
+- [@nestjs-modules/mailer on npm](https://www.npmjs.com/package/@nestjs-modules/mailer)
+- [@nestjs-modules/mailer on GitHub](https://github.com/nest-modules/mailer)
+
+## Dependencies
+
+| Package                  | Version  | Purpose               |
+| ------------------------ | -------- | --------------------- |
+| `@nestjs-modules/mailer` | `2.0.2`  | NestJS mailer module  |
+| `nodemailer`             | `6.9.16` | SMTP transport        |
+| `handlebars`             | `4.7.8`  | Email template engine |
+
+## Environment Variables
+
+| Variable        | Description            | Example               |
+| --------------- | ---------------------- | --------------------- |
+| `MAIL_HOST`     | SMTP server hostname   | `smtp.example.com`    |
+| `MAIL_PORT`     | SMTP port              | `587`                 |
+| `MAIL_USER`     | SMTP username          | `noreply@example.com` |
+| `MAIL_PASSWORD` | SMTP password          | `secret`              |
+| `MAIL_FROM`     | Default "from" address | `noreply@example.com` |
+
+## Usage
+
+```typescript
+import { MailModule } from '@/infrastructure/notifications/mail.module';
+
+@Module({
+  imports: [MailModule],
+})
+export class AppModule {}
+
+// In a service
+constructor(private readonly mailer: MailerService) {}
+
+await this.mailer.sendMail({
+  to: 'user@example.com',
+  subject: 'Welcome',
+  template: 'welcome',
+  context: { name: 'Alice' },
+});
+```
+
+## Generated Files
+
+| File                                              | Description                                     |
+| ------------------------------------------------- | ----------------------------------------------- |
+| `src/infrastructure/notifications/mail.module.ts` | Mailer module with SMTP transport configuration |

package/templates/recipes/nodemailer/src/infrastructure/notifications/mail.module.ts

@@ -0,0 +1,37 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { MailerModule } from '@nestjs-modules/mailer';
+import { HandlebarsAdapter } from '@nestjs-modules/mailer/dist/adapters/handlebars.adapter';
+import { join } from 'node:path';
+
+@Module({
+  imports: [
+    MailerModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        transport: {
+          host: config.getOrThrow<string>('MAIL_HOST'),
+          port: config.getOrThrow<number>('MAIL_PORT'),
+          secure: config.get<number>('MAIL_PORT') === 465,
+          auth: {
+            user: config.getOrThrow<string>('MAIL_USER'),
+            pass: config.getOrThrow<string>('MAIL_PASSWORD'),
+          },
+        },
+        defaults: {
+          from: config.getOrThrow<string>('MAIL_FROM'),
+        },
+        template: {
+          dir: join(__dirname, '..', '..', 'templates', 'mail'),
+          adapter: new HandlebarsAdapter(),
+          options: {
+            strict: true,
+          },
+        },
+      }),
+    }),
+  ],
+  exports: [MailerModule],
+})
+export class MailModule {}

package/templates/recipes/nodemailer/tests/unit/infrastructure/notifications/mail.module.spec.ts

@@ -0,0 +1,33 @@
+import { ConfigService } from '@nestjs/config';
+
+describe('MailModule', () => {
+  it('should resolve transport config from environment variables', () => {
+    const configService = new ConfigService({
+      MAIL_HOST: 'smtp.example.com',
+      MAIL_PORT: 587,
+      MAIL_USER: 'user@example.com',
+      MAIL_PASSWORD: 'password',
+      MAIL_FROM: 'noreply@example.com',
+    });
+
+    expect(configService.getOrThrow('MAIL_HOST')).toBe('smtp.example.com');
+    expect(configService.getOrThrow('MAIL_PORT')).toBe(587);
+    expect(configService.getOrThrow('MAIL_USER')).toBe('user@example.com');
+    expect(configService.getOrThrow('MAIL_PASSWORD')).toBe('password');
+    expect(configService.getOrThrow('MAIL_FROM')).toBe('noreply@example.com');
+  });
+
+  it('should detect secure transport on port 465', () => {
+    const configService = new ConfigService({ MAIL_PORT: 465 });
+    const port = configService.get<number>('MAIL_PORT');
+    const secure = port === 465;
+    expect(secure).toBe(true);
+  });
+
+  it('should not use secure transport on port 587', () => {
+    const configService = new ConfigService({ MAIL_PORT: 587 });
+    const port = configService.get<number>('MAIL_PORT');
+    const secure = port === 465;
+    expect(secure).toBe(false);
+  });
+});

package/templates/recipes/oauth-apple/README.md

@@ -0,0 +1,68 @@
+# Sign in with Apple
+
+Apple OAuth login strategy using Passport for NestJS applications.
+
+## Links
+
+- [Sign in with Apple Documentation](https://developer.apple.com/sign-in-with-apple/)
+- [Apple Developer Portal - Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list)
+- [Configuring Your Environment for Sign in with Apple](https://developer.apple.com/documentation/sign_in_with_apple/configuring_your_environment_for_sign_in_with_apple)
+- [NestJS Authentication Documentation](https://docs.nestjs.com/security/authentication)
+- [passport-apple on npm](https://www.npmjs.com/package/passport-apple)
+- [@nestjs/passport on npm](https://www.npmjs.com/package/@nestjs/passport)
+
+## Dependencies
+
+| Package            | Version  | Purpose                           |
+| ------------------ | -------- | --------------------------------- |
+| `passport-apple`   | `2.0.2`  | Apple OAuth strategy for Passport |
+| `@nestjs/passport` | `10.0.3` | Passport integration for NestJS   |
+| `passport`         | `0.7.0`  | Authentication middleware         |
+
+## Setup
+
+1. Go to the [Apple Developer Portal](https://developer.apple.com/account/resources/identifiers/list).
+2. Register an **App ID** with **Sign In with Apple** capability enabled.
+3. Register a **Services ID** (this becomes your `APPLE_CLIENT_ID`).
+4. Configure the **Web Authentication Configuration** on the Services ID with your domain and callback URL.
+5. Create a **Sign In with Apple** private key under **Keys**. Download the `.p8` file.
+6. Note your **Team ID** (top-right of the developer portal), the **Key ID**, and the path to the `.p8` file.
+
+## Environment Variables
+
+| Variable                 | Description                                       |
+| ------------------------ | ------------------------------------------------- |
+| `APPLE_CLIENT_ID`        | Apple Services ID (e.g. `com.example.app`)        |
+| `APPLE_TEAM_ID`          | Apple Developer Team ID                           |
+| `APPLE_KEY_ID`           | Key ID for the Sign In with Apple private key     |
+| `APPLE_PRIVATE_KEY_PATH` | File system path to the `.p8` private key file    |
+| `APPLE_CALLBACK_URL`     | Callback URL registered in Apple Developer Portal |
+
+## Usage
+
+```typescript
+@Controller('auth')
+export class AuthController {
+  @Get('apple')
+  @UseGuards(AppleAuthGuard)
+  appleLogin() {
+    // Redirects to Apple login page
+  }
+
+  @Post('apple/callback')
+  @UseGuards(AppleAuthGuard)
+  appleCallback(@Request() req) {
+    // Apple sends a POST to the callback URL
+    return req.user;
+  }
+}
+```
+
+**Important:** Apple only returns the user's name and email on the **first** authorization. Store this information on the initial login.
+
+## Generated Files
+
+| File                                  | Description                                     |
+| ------------------------------------- | ----------------------------------------------- |
+| `src/shared/auth/apple.strategy.ts`   | Apple OAuth Passport strategy                   |
+| `src/shared/auth/apple-auth.guard.ts` | Auth guard wrapping the Apple Passport strategy |

package/templates/recipes/oauth-apple/src/shared/auth/apple-auth.guard.ts

@@ -0,0 +1,5 @@
+import { Injectable } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+
+@Injectable()
+export class AppleAuthGuard extends AuthGuard('apple') {}

package/templates/recipes/oauth-apple/src/shared/auth/apple.strategy.ts

@@ -0,0 +1,33 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { PassportStrategy } from '@nestjs/passport';
+import { Strategy } from 'passport-apple';
+
+@Injectable()
+export class AppleStrategy extends PassportStrategy(Strategy, 'apple') {
+  constructor(private readonly configService: ConfigService) {
+    super({
+      clientID: configService.getOrThrow<string>('APPLE_CLIENT_ID'),
+      teamID: configService.getOrThrow<string>('APPLE_TEAM_ID'),
+      keyID: configService.getOrThrow<string>('APPLE_KEY_ID'),
+      privateKeyPath: configService.getOrThrow<string>('APPLE_PRIVATE_KEY_PATH'),
+      callbackURL: configService.getOrThrow<string>('APPLE_CALLBACK_URL'),
+      scope: ['name', 'email'],
+    });
+  }
+
+  validate(
+    accessToken: string,
+    refreshToken: string,
+    decodedIdToken: { sub: string; email?: string },
+    done: (err: Error | null, user?: Record<string, unknown>) => void,
+  ): void {
+    const user = {
+      provider: 'apple',
+      providerId: decodedIdToken.sub,
+      email: decodedIdToken.email,
+      accessToken,
+    };
+    done(null, user);
+  }
+}

package/templates/recipes/oauth-apple/tests/unit/shared/auth/apple.strategy.spec.ts

@@ -0,0 +1,65 @@
+import { ConfigService } from '@nestjs/config';
+import { Test } from '@nestjs/testing';
+import { AppleStrategy } from '@/shared/auth/apple.strategy';
+
+describe('AppleStrategy', () => {
+  let strategy: AppleStrategy;
+
+  const mockConfigService = {
+    getOrThrow: jest.fn((key: string) => {
+      const config: Record<string, string> = {
+        APPLE_CLIENT_ID: 'com.example.app',
+        APPLE_TEAM_ID: 'TEAM123',
+        APPLE_KEY_ID: 'KEY456',
+        APPLE_PRIVATE_KEY_PATH: '/path/to/key.p8',
+        APPLE_CALLBACK_URL: 'http://localhost:3000/auth/apple/callback',
+      };
+      return config[key];
+    }),
+  };
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [AppleStrategy, { provide: ConfigService, useValue: mockConfigService }],
+    }).compile();
+
+    strategy = module.get(AppleStrategy);
+  });
+
+  it('should be defined', () => {
+    expect(strategy).toBeDefined();
+  });
+
+  it('should extract user from Apple decoded ID token', () => {
+    const decodedIdToken = {
+      sub: 'apple-user-001',
+      email: 'user@privaterelay.appleid.com',
+    };
+    const done = jest.fn();
+
+    strategy.validate('access-token', 'refresh-token', decodedIdToken, done);
+
+    expect(done).toHaveBeenCalledWith(null, {
+      provider: 'apple',
+      providerId: 'apple-user-001',
+      email: 'user@privaterelay.appleid.com',
+      accessToken: 'access-token',
+    });
+  });
+
+  it('should handle decoded ID token without email', () => {
+    const decodedIdToken = {
+      sub: 'apple-user-002',
+    };
+    const done = jest.fn();
+
+    strategy.validate('access-token', 'refresh-token', decodedIdToken as any, done);
+
+    expect(done).toHaveBeenCalledWith(null, {
+      provider: 'apple',
+      providerId: 'apple-user-002',
+      email: undefined,
+      accessToken: 'access-token',
+    });
+  });
+});

package/templates/recipes/oauth-github/README.md

@@ -0,0 +1,62 @@
+# GitHub OAuth
+
+GitHub OAuth login strategy using Passport for NestJS applications.
+
+## Links
+
+- [GitHub OAuth Apps Documentation](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)
+- [GitHub Developer Settings](https://github.com/settings/developers)
+- [NestJS Authentication Documentation](https://docs.nestjs.com/security/authentication)
+- [passport-github2 on npm](https://www.npmjs.com/package/passport-github2)
+- [@nestjs/passport on npm](https://www.npmjs.com/package/@nestjs/passport)
+
+## Dependencies
+
+| Package                   | Version  | Purpose                                     |
+| ------------------------- | -------- | ------------------------------------------- |
+| `passport-github2`        | `0.1.12` | GitHub OAuth 2.0 strategy for Passport      |
+| `@nestjs/passport`        | `10.0.3` | Passport integration for NestJS             |
+| `passport`                | `0.7.0`  | Authentication middleware                   |
+| `@types/passport-github2` | `1.2.9`  | TypeScript definitions for passport-github2 |
+
+## Setup
+
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers).
+2. Click **New OAuth App**.
+3. Fill in the application name, homepage URL, and callback URL (e.g. `http://localhost:3000/auth/github/callback`).
+4. Click **Register application**.
+5. Copy the **Client ID** and generate a **Client Secret** into your environment variables.
+
+## Environment Variables
+
+| Variable               | Description                                            |
+| ---------------------- | ------------------------------------------------------ |
+| `GITHUB_CLIENT_ID`     | OAuth App client ID from GitHub Developer Settings     |
+| `GITHUB_CLIENT_SECRET` | OAuth App client secret from GitHub Developer Settings |
+| `GITHUB_CALLBACK_URL`  | Callback URL registered in GitHub Developer Settings   |
+
+## Usage
+
+```typescript
+@Controller('auth')
+export class AuthController {
+  @Get('github')
+  @UseGuards(GitHubAuthGuard)
+  githubLogin() {
+    // Redirects to GitHub login page
+  }
+
+  @Get('github/callback')
+  @UseGuards(GitHubAuthGuard)
+  githubCallback(@Request() req) {
+    return req.user;
+  }
+}
+```
+
+## Generated Files
+
+| File                                   | Description                                      |
+| -------------------------------------- | ------------------------------------------------ |
+| `src/shared/auth/github.strategy.ts`   | GitHub OAuth Passport strategy                   |
+| `src/shared/auth/github-auth.guard.ts` | Auth guard wrapping the GitHub Passport strategy |

package/templates/recipes/oauth-github/src/shared/auth/github-auth.guard.ts

@@ -0,0 +1,5 @@
+import { Injectable } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+
+@Injectable()
+export class GitHubAuthGuard extends AuthGuard('github') {}

package/templates/recipes/oauth-github/src/shared/auth/github.strategy.ts

@@ -0,0 +1,33 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { PassportStrategy } from '@nestjs/passport';
+import { Profile, Strategy } from 'passport-github2';
+
+@Injectable()
+export class GitHubStrategy extends PassportStrategy(Strategy, 'github') {
+  constructor(private readonly configService: ConfigService) {
+    super({
+      clientID: configService.getOrThrow<string>('GITHUB_CLIENT_ID'),
+      clientSecret: configService.getOrThrow<string>('GITHUB_CLIENT_SECRET'),
+      callbackURL: configService.getOrThrow<string>('GITHUB_CALLBACK_URL'),
+      scope: ['user:email'],
+    });
+  }
+
+  validate(
+    accessToken: string,
+    refreshToken: string,
+    profile: Profile,
+    done: (err: Error | null, user?: Record<string, unknown>) => void,
+  ): void {
+    const user = {
+      provider: 'github',
+      providerId: profile.id,
+      email: profile.emails?.[0]?.value,
+      name: profile.displayName,
+      avatar: profile.photos?.[0]?.value,
+      accessToken,
+    };
+    done(null, user);
+  }
+}