@podosoft/podokit 0.1.1 → 0.3.0

package/dist/templates/modules/audit-log/module.manifest.json

@@ -0,0 +1,16 @@
+{
+  "name": "audit-log",
+  "description": "Audit logging: a global interceptor records who did each mutating request (who/method/path/status) to an audit_logs table. Requires auth.",
+  "requires": ["auth"],
+  "targetApp": "api",
+  "env": [],
+  "inject": [
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { AuditModule } from \"./audit/audit.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "AuditModule," }
+  ],
+  "instructions": [
+    "Run migrations to create the audit_logs table:  npm run migration:run -w <app>-api",
+    "Mutating requests (POST/PUT/PATCH/DELETE) are recorded with the acting user.",
+    "List recent entries (requires a session):  curl -b cookies.txt localhost:3000/audit-logs"
+  ]
+}

package/dist/templates/modules/auth/files/apps/api/src/account/account.controller.ts

@@ -0,0 +1,13 @@
+import { Controller, Get } from "@nestjs/common";
+import { Session, type UserSession } from "@thallesp/nestjs-better-auth";
+import { ApiTags } from "@nestjs/swagger";
+
+// Protected by the global AuthGuard. Use @Session() to read the current user.
+@ApiTags("account")
+@Controller("account")
+export class AccountController {
+  @Get("me")
+  me(@Session() session: UserSession) {
+    return session.user;
+  }
+}

package/dist/templates/modules/auth/files/apps/api/src/account/account.module.ts

@@ -0,0 +1,5 @@
+import { Module } from "@nestjs/common";
+import { AccountController } from "./account.controller";
+
+@Module({ controllers: [AccountController] })
+export class AccountModule {}

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.ts

@@ -0,0 +1,36 @@
+import { betterAuth, type BetterAuthOptions } from "better-auth";
+import { twoFactor } from "better-auth/plugins";
+import { Pool } from "pg";
+
+// OAuth providers are enabled only when their credentials are present.
+function socialProviders(): NonNullable<BetterAuthOptions["socialProviders"]> {
+  const providers: NonNullable<BetterAuthOptions["socialProviders"]> = {};
+  if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+    providers.google = {
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+    };
+  }
+  if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
+    providers.github = {
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+    };
+  }
+  return providers;
+}
+
+export const auth = betterAuth({
+  database: new Pool({
+    host: process.env.POSTGRES_HOST ?? "localhost",
+    port: Number(process.env.POSTGRES_PORT ?? 5432),
+    user: process.env.POSTGRES_USER ?? "podokit",
+    password: process.env.POSTGRES_PASSWORD ?? "podokit",
+    database: process.env.POSTGRES_DB ?? "podokit",
+  }),
+  emailAndPassword: { enabled: true },
+  socialProviders: socialProviders(),
+  plugins: process.env.AUTH_TWO_FACTOR === "true" ? [twoFactor()] : [],
+  secret: process.env.BETTER_AUTH_SECRET ?? "change-me-in-production-min-32-characters",
+  baseURL: process.env.BETTER_AUTH_URL ?? "http://localhost:3000",
+});

package/dist/templates/modules/auth/files/apps/api/src/health/health.controller.ts

@@ -0,0 +1,26 @@
+import { Controller, Get } from "@nestjs/common";
+import { InjectDataSource } from "@nestjs/typeorm";
+import { DataSource } from "typeorm";
+import { Public } from "@thallesp/nestjs-better-auth";
+
+// Health checks stay public under the global auth guard.
+@Public()
+@Controller("health")
+export class HealthController {
+  constructor(@InjectDataSource() private readonly dataSource: DataSource) {}
+
+  @Get()
+  liveness(): { status: string; uptime: number; timestamp: string } {
+    return { status: "ok", uptime: process.uptime(), timestamp: new Date().toISOString() };
+  }
+
+  @Get("ready")
+  async readiness(): Promise<{ status: string; db: string }> {
+    try {
+      await this.dataSource.query("SELECT 1");
+      return { status: "ready", db: "up" };
+    } catch {
+      return { status: "degraded", db: "down" };
+    }
+  }
+}

package/dist/templates/modules/auth/module.manifest.json

@@ -0,0 +1,70 @@
+{
+  "name": "auth",
+  "description": "Full authentication (better-auth): email/password, sessions, and \u2014 via config \u2014 OAuth and 2FA. Installs a global guard so the API is secure by default; health and /api/auth stay public.",
+  "requires": [],
+  "targetApp": "api",
+  "dependencies": {
+    "better-auth": "^1.6.23",
+    "@thallesp/nestjs-better-auth": "^2.7.0",
+    "pg": "^8.12.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.10"
+  },
+  "env": [
+    "# auth (better-auth) \u2014 set a strong secret (>= 32 chars) in production",
+    "BETTER_AUTH_SECRET=change-me-in-production-min-32-characters",
+    "BETTER_AUTH_URL=http://localhost:3000",
+    "# 2FA (TOTP): set true to enable the plugin",
+    "AUTH_TWO_FACTOR=false",
+    "# OAuth (optional) \u2014 set a provider's id+secret to enable it",
+    "# GOOGLE_CLIENT_ID=",
+    "# GOOGLE_CLIENT_SECRET=",
+    "# GITHUB_CLIENT_ID=",
+    "# GITHUB_CLIENT_SECRET="
+  ],
+  "inject": [
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:imports",
+      "text": "import { APP_GUARD } from \"@nestjs/core\";"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:imports",
+      "text": "import { AuthModule, AuthGuard } from \"@thallesp/nestjs-better-auth\";"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:imports",
+      "text": "import { auth } from \"./auth/auth\";"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:imports",
+      "text": "import { AccountModule } from \"./account/account.module\";"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:module-imports",
+      "text": "AuthModule.forRoot(auth),"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:module-imports",
+      "text": "AccountModule,"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:providers",
+      "text": "{ provide: APP_GUARD, useClass: AuthGuard },"
+    }
+  ],
+  "instructions": [
+    "Set BETTER_AUTH_SECRET in .env (>= 32 chars).",
+    "Create the auth tables:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
+    "Sign up:  curl -c cookies.txt -XPOST localhost:3000/api/auth/sign-up/email -H 'content-type: application/json' -d '{\"email\":\"a@example.com\",\"password\":\"password123\",\"name\":\"A\"}'",
+    "Call a protected route with the session:  curl -b cookies.txt localhost:3000/account/me",
+    "Everything is now protected by default; mark public routes with @Public(). Enable OAuth by setting a provider's env vars; enable 2FA with AUTH_TWO_FACTOR=true."
+  ]
+}

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/demo.processor.ts

@@ -0,0 +1,12 @@
+import { Processor, WorkerHost } from "@nestjs/bullmq";
+import type { Job } from "bullmq";
+import { DEMO_QUEUE } from "./queue";
+
+@Processor(DEMO_QUEUE)
+export class DemoProcessor extends WorkerHost {
+  async process(job: Job<{ text: string }>): Promise<{ upper: string }> {
+    // Simulate work.
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    return { upper: String(job.data.text ?? "").toUpperCase() };
+  }
+}

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/dto/create-job.dto.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsNotEmpty, IsString } from "class-validator";
+
+export class CreateJobDto {
+  @ApiProperty({ example: "hello" })
+  @IsString()
+  @IsNotEmpty()
+  text!: string;
+}

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/jobs.controller.ts

@@ -0,0 +1,29 @@
+import { Body, Controller, Get, NotFoundException, Param, Post } from "@nestjs/common";
+import { InjectQueue } from "@nestjs/bullmq";
+import { ApiTags } from "@nestjs/swagger";
+import { Queue } from "bullmq";
+import { CreateJobDto } from "./dto/create-job.dto";
+import { DEMO_QUEUE } from "./queue";
+
+@ApiTags("jobs")
+@Controller("jobs")
+export class JobsController {
+  constructor(@InjectQueue(DEMO_QUEUE) private readonly queue: Queue) {}
+
+  @Post()
+  async enqueue(@Body() dto: CreateJobDto): Promise<{ id: string | undefined }> {
+    const job = await this.queue.add("demo", { text: dto.text });
+    return { id: job.id };
+  }
+
+  @Get(":id")
+  async status(
+    @Param("id") id: string,
+  ): Promise<{ id: string | undefined; state: string; result: unknown }> {
+    const job = await this.queue.getJob(id);
+    if (!job) {
+      throw new NotFoundException(`Job ${id} not found`);
+    }
+    return { id: job.id, state: await job.getState(), result: job.returnvalue ?? null };
+  }
+}

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/jobs.module.ts

@@ -0,0 +1,15 @@
+import { Module } from "@nestjs/common";
+import { BullModule } from "@nestjs/bullmq";
+import { JobsController } from "./jobs.controller";
+import { DEMO_QUEUE, redisConnection } from "./queue";
+
+// Producer side: registers the queue and exposes enqueue/status endpoints.
+// The processor runs in a separate worker process (see main-worker.ts).
+@Module({
+  imports: [
+    BullModule.forRoot({ connection: redisConnection() }),
+    BullModule.registerQueue({ name: DEMO_QUEUE }),
+  ],
+  controllers: [JobsController],
+})
+export class JobsModule {}

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/queue.ts

@@ -0,0 +1,8 @@
+export const DEMO_QUEUE = "demo";
+
+export function redisConnection(): { host: string; port: number } {
+  return {
+    host: process.env.REDIS_HOST ?? "localhost",
+    port: Number(process.env.REDIS_PORT ?? 6379),
+  };
+}

package/dist/templates/modules/bullmq/files/apps/api/src/jobs/worker.module.ts

@@ -0,0 +1,20 @@
+import { Module } from "@nestjs/common";
+import { BullModule } from "@nestjs/bullmq";
+import { DemoProcessor } from "./demo.processor";
+import { DEMO_QUEUE, redisConnection } from "./queue";
+// podokit:worker-imports
+
+// Consumer side: runs BullMQ processors. Bootstrapped by main-worker.ts as a
+// separate process so workers scale independently of the API.
+@Module({
+  imports: [
+    BullModule.forRoot({ connection: redisConnection() }),
+    BullModule.registerQueue({ name: DEMO_QUEUE }),
+    // podokit:worker-queues
+  ],
+  providers: [
+    DemoProcessor,
+    // podokit:worker-providers
+  ],
+})
+export class WorkerModule {}

package/dist/templates/modules/bullmq/files/apps/api/src/main-worker.ts

@@ -0,0 +1,14 @@
+import "dotenv/config";
+import { NestFactory } from "@nestjs/core";
+import { WorkerModule } from "./jobs/worker.module";
+
+// Runs BullMQ processors in their own process (no HTTP server).
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.createApplicationContext(WorkerModule);
+  await app.init();
+  // Keep the process alive to consume jobs.
+  process.on("SIGINT", () => void app.close().then(() => process.exit(0)));
+  process.on("SIGTERM", () => void app.close().then(() => process.exit(0)));
+}
+
+void bootstrap();

package/dist/templates/modules/bullmq/files/infra/docker/worker.compose.example.yml

@@ -0,0 +1,18 @@
+# Example: run the BullMQ worker as its own service.
+#
+# The default infra/docker/docker-compose.yml is dev infra (PostgreSQL + Redis)
+# only, with the app running on the host. For a fully containerized deployment,
+# build the API image and run the worker entrypoint against it — for example:
+#
+#   docker compose -f infra/docker/docker-compose.yml -f infra/docker/worker.compose.example.yml up -d
+services:
+  worker:
+    build:
+      context: ../../apps/api
+    command: ["node", "dist/main-worker"]
+    environment:
+      REDIS_HOST: redis
+      REDIS_PORT: "6379"
+    depends_on:
+      redis:
+        condition: service_healthy

package/dist/templates/modules/bullmq/files/infra/k3s/worker-deployment.yaml

@@ -0,0 +1,22 @@
+# BullMQ worker — runs the same API image with the worker entrypoint.
+# It has no HTTP server, so there is no Service or Ingress.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: worker
+  namespace: podokit
+spec:
+  replicas: 1
+  selector:
+    matchLabels: { app: worker }
+  template:
+    metadata:
+      labels: { app: worker }
+    spec:
+      containers:
+        - name: worker
+          image: ghcr.io/example/podokit-api:latest
+          command: ["node", "dist/main-worker"]
+          envFrom:
+            - configMapRef: { name: app-config }
+            - secretRef: { name: app-secrets }

package/dist/templates/modules/bullmq/module.manifest.json

@@ -0,0 +1,36 @@
+{
+  "name": "bullmq",
+  "description": "Background jobs with BullMQ: a demo queue, a separate worker process, and enqueue/status endpoints (needs Redis).",
+  "requires": [],
+  "targetApp": "api",
+  "dependencies": {
+    "@nestjs/bullmq": "^11.0.4",
+    "bullmq": "^5.34.0"
+  },
+  "scripts": {
+    "start:worker": "node dist/main-worker",
+    "dev:worker": "nest start --watch --entryFile main-worker"
+  },
+  "env": [
+    "# bullmq uses REDIS_HOST / REDIS_PORT (already defined above)"
+  ],
+  "inject": [
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:imports",
+      "text": "import { JobsModule } from \"./jobs/jobs.module\";"
+    },
+    {
+      "file": "apps/api/src/app.module.ts",
+      "marker": "// podokit:module-imports",
+      "text": "JobsModule,"
+    }
+  ],
+  "instructions": [
+    "Ensure Redis is running:  docker compose -f infra/docker/docker-compose.yml up -d",
+    "Run the worker in a separate terminal:  npm run dev:worker -w <app>-api",
+    "Enqueue a job:  curl -XPOST localhost:3000/jobs -H 'content-type: application/json' -d '{\"text\":\"hello\"}'",
+    "Check status:   curl localhost:3000/jobs/<id>  (state goes waiting -> active -> completed)",
+    "Deploy the worker as its own process: k3s manifest added at infra/k3s/worker-deployment.yaml; Docker Compose example at infra/docker/worker.compose.example.yml"
+  ]
+}

package/dist/templates/modules/file-upload/files/apps/api/src/files/files.controller.ts

@@ -0,0 +1,29 @@
+import { BadRequestException, Controller, Get, Param, Post, UploadedFile, UseInterceptors } from "@nestjs/common";
+import { FileInterceptor } from "@nestjs/platform-express";
+import { ApiConsumes, ApiTags } from "@nestjs/swagger";
+import { randomUUID } from "node:crypto";
+import { StorageService } from "../storage/storage.service";
+
+@ApiTags("files")
+@Controller("files")
+export class FilesController {
+  constructor(private readonly storage: StorageService) {}
+
+  @Post()
+  @ApiConsumes("multipart/form-data")
+  @UseInterceptors(FileInterceptor("file"))
+  async upload(@UploadedFile() file?: Express.Multer.File): Promise<{ key: string; url: string }> {
+    if (!file) {
+      throw new BadRequestException("A file field is required (multipart/form-data)");
+    }
+    const safeName = file.originalname.replace(/[^\w.-]+/g, "_");
+    const key = `uploads/${randomUUID()}-${safeName}`;
+    await this.storage.put(key, file.buffer, file.mimetype);
+    return { key, url: await this.storage.presignedGetUrl(key) };
+  }
+
+  @Get(":key/url")
+  async url(@Param("key") key: string): Promise<{ url: string }> {
+    return { url: await this.storage.presignedGetUrl(key) };
+  }
+}

package/dist/templates/modules/file-upload/files/apps/api/src/files/files.module.ts

@@ -0,0 +1,9 @@
+import { Module } from "@nestjs/common";
+import { FilesController } from "./files.controller";
+
+// Uploads are stored through StorageService, provided globally by the
+// object-storage-s3 module.
+@Module({
+  controllers: [FilesController],
+})
+export class FilesModule {}

package/dist/templates/modules/file-upload/module.manifest.json

@@ -0,0 +1,19 @@
+{
+  "name": "file-upload",
+  "description": "Multipart file upload endpoint that stores files via object storage and returns a presigned URL.",
+  "requires": ["object-storage-s3"],
+  "targetApp": "api",
+  "devDependencies": {
+    "@types/multer": "^1.4.12"
+  },
+  "env": [],
+  "inject": [
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { FilesModule } from \"./files/files.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "FilesModule," }
+  ],
+  "instructions": [
+    "Start MinIO (or configure AWS S3):  docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml up -d",
+    "Upload a file:  curl -F 'file=@./some.png' localhost:3000/files",
+    "The response includes { key, url } — a presigned download URL."
+  ]
+}

package/dist/templates/modules/job-progress/files/apps/api/src/progress/dto/start-job.dto.ts

@@ -0,0 +1,11 @@
+import { ApiPropertyOptional } from "@nestjs/swagger";
+import { IsInt, IsOptional, Max, Min } from "class-validator";
+
+export class StartJobDto {
+  @ApiPropertyOptional({ example: 5, description: "Number of progress steps" })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  steps?: number;
+}

package/dist/templates/modules/job-progress/files/apps/api/src/progress/job-progress.module.ts

@@ -0,0 +1,13 @@
+import { Module } from "@nestjs/common";
+import { BullModule } from "@nestjs/bullmq";
+import { ProgressController } from "./progress.controller";
+import { ProgressBridge } from "./progress.bridge";
+
+// API side: enqueue progress jobs and relay their progress to SSE.
+// RedisService and EventsService are provided globally by their modules.
+@Module({
+  imports: [BullModule.registerQueue({ name: "progress" })],
+  controllers: [ProgressController],
+  providers: [ProgressBridge],
+})
+export class JobProgressModule {}

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.bridge.ts

@@ -0,0 +1,19 @@
+import { Injectable, type OnModuleInit } from "@nestjs/common";
+import { RedisService } from "../redis/redis.service";
+import { EventsService } from "../events/events.service";
+import { PROGRESS_CHANNEL } from "./progress.processor";
+
+// Runs in the API process: relays worker progress (Redis pub/sub) to SSE.
+@Injectable()
+export class ProgressBridge implements OnModuleInit {
+  constructor(
+    private readonly redis: RedisService,
+    private readonly events: EventsService,
+  ) {}
+
+  onModuleInit(): void {
+    this.redis.subscribe(PROGRESS_CHANNEL, (message) => {
+      this.events.publish({ type: "job-progress", ...JSON.parse(message) });
+    });
+  }
+}

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.controller.ts

@@ -0,0 +1,17 @@
+import { Body, Controller, Post } from "@nestjs/common";
+import { InjectQueue } from "@nestjs/bullmq";
+import { ApiTags } from "@nestjs/swagger";
+import { Queue } from "bullmq";
+import { StartJobDto } from "./dto/start-job.dto";
+
+@ApiTags("progress")
+@Controller("progress")
+export class ProgressController {
+  constructor(@InjectQueue("progress") private readonly queue: Queue) {}
+
+  @Post()
+  async start(@Body() dto: StartJobDto): Promise<{ jobId: string | undefined }> {
+    const job = await this.queue.add("progress", { steps: dto.steps ?? 5 });
+    return { jobId: job.id };
+  }
+}

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.processor.ts

@@ -0,0 +1,25 @@
+import { Processor, WorkerHost } from "@nestjs/bullmq";
+import type { Job } from "bullmq";
+import { RedisService } from "../redis/redis.service";
+
+export const PROGRESS_CHANNEL = "job:progress";
+
+// Runs in the worker process. Reports progress both to BullMQ and, via Redis
+// pub/sub, to the API process (which relays it to SSE clients).
+@Processor("progress")
+export class ProgressProcessor extends WorkerHost {
+  constructor(private readonly redis: RedisService) {
+    super();
+  }
+
+  async process(job: Job<{ steps?: number }>): Promise<{ done: true }> {
+    const steps = job.data.steps ?? 5;
+    for (let i = 1; i <= steps; i += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 400));
+      const progress = Math.round((i / steps) * 100);
+      await job.updateProgress(progress);
+      await this.redis.publish(PROGRESS_CHANNEL, JSON.stringify({ jobId: job.id, progress }));
+    }
+    return { done: true };
+  }
+}

package/dist/templates/modules/job-progress/module.manifest.json

@@ -0,0 +1,23 @@
+{
+  "name": "job-progress",
+  "description": "Live job progress: a worker reports progress over Redis pub/sub and the API relays it to SSE clients (combines bullmq + redis + sse).",
+  "requires": ["bullmq", "sse", "redis"],
+  "targetApp": "api",
+  "env": [],
+  "inject": [
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { JobProgressModule } from \"./progress/job-progress.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "JobProgressModule," },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:worker-imports", "text": "import { ProgressProcessor } from \"../progress/progress.processor\";" },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:worker-imports", "text": "import { RedisModule } from \"../redis/redis.module\";" },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:worker-queues", "text": "RedisModule," },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:worker-queues", "text": "BullModule.registerQueue({ name: \"progress\" })," },
+    { "file": "apps/api/src/jobs/worker.module.ts", "marker": "// podokit:worker-providers", "text": "ProgressProcessor," }
+  ],
+  "instructions": [
+    "Start Redis + Postgres:  docker compose -f infra/docker/docker-compose.yml up -d",
+    "Run API and worker in separate terminals:  npm run dev   /   npm run dev:worker -w <app>-api",
+    "Watch progress:  curl -N localhost:3000/events/stream",
+    "Start a job:     curl -XPOST localhost:3000/progress -H 'content-type: application/json' -d '{\"steps\":5}'",
+    "The stream shows job-progress events 20 -> 40 -> ... -> 100 pushed from the worker via Redis."
+  ]
+}

package/dist/templates/modules/logging/files/apps/api/src/logging/logging.module.ts

@@ -0,0 +1,29 @@
+import { Module } from "@nestjs/common";
+import { randomUUID } from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { LoggerModule } from "nestjs-pino";
+
+const isProduction = process.env.NODE_ENV === "production";
+
+// Structured request logging with a correlation id. Importing this module
+// installs the pino-http middleware for all routes.
+@Module({
+  imports: [
+    LoggerModule.forRoot({
+      pinoHttp: {
+        level: process.env.LOG_LEVEL ?? "info",
+        // Pretty, single-line logs in dev; JSON in production.
+        transport: isProduction ? undefined : { target: "pino-pretty", options: { singleLine: true } },
+        autoLogging: true,
+        // One id per request; honor an inbound x-request-id and echo it back.
+        genReqId: (req: IncomingMessage, res: ServerResponse): string => {
+          const header = req.headers["x-request-id"];
+          const id = (Array.isArray(header) ? header[0] : header) ?? randomUUID();
+          res.setHeader("x-request-id", id);
+          return id;
+        },
+      },
+    }),
+  ],
+})
+export class LoggingModule {}

package/dist/templates/modules/logging/module.manifest.json

@@ -0,0 +1,27 @@
+{
+  "name": "logging",
+  "description": "Structured request logging (nestjs-pino) with a per-request correlation id (x-request-id). Pretty in dev, JSON in production.",
+  "requires": [],
+  "targetApp": "api",
+  "dependencies": {
+    "nestjs-pino": "^4.3.0",
+    "pino-http": "^10.3.0"
+  },
+  "devDependencies": {
+    "pino-pretty": "^13.0.0"
+  },
+  "env": [
+    "# logging",
+    "LOG_LEVEL=info"
+  ],
+  "inject": [
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:imports", "text": "import { LoggingModule } from \"./logging/logging.module\";" },
+    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:module-imports", "text": "LoggingModule," }
+  ],
+  "instructions": [
+    "Every HTTP request is now logged as structured JSON with a correlation id.",
+    "Make a request and watch the API logs:  curl localhost:3000/health",
+    "Set LOG_LEVEL (debug|info|warn|error) in .env. Logs are pretty in dev and JSON when NODE_ENV=production.",
+    "To route Nest's own logs through pino too, add to main.ts: NestFactory.create(AppModule, { bufferLogs: true }) then app.useLogger(app.get(Logger))."
+  ]
+}

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/dto/put-object.dto.ts

@@ -0,0 +1,8 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsString } from "class-validator";
+
+export class PutObjectDto {
+  @ApiProperty({ example: "hello world" })
+  @IsString()
+  content!: string;
+}