@miguelmorales13/nestkit 0.1.1 → 0.3.0

package/README.md

@@ -387,6 +387,304 @@ El idioma se resuelve por el `Accept-Language` del request (comportamiento por d
 regresa el `fallback`, así una traducción faltante no se convierte en un error 500 encima del error
 original.
 
+### `telegram` — cliente de salida para un bot específico
+
+```ts
+import { Module } from '@nestjs/common';
+import { TelegramModule } from '@miguelmorales13/nestkit/telegram';
+
+@Module({ imports: [TelegramModule] })
+export class AppModule {}
+```
+
+```ts
+import { Inject, Injectable } from '@nestjs/common';
+import { TELEGRAM_BOT } from '@miguelmorales13/nestkit/telegram';
+import type { Telegram as TelegramClient } from 'telegraf';
+
+@Injectable()
+export class NotificationsService {
+  constructor(@Inject(TELEGRAM_BOT) private readonly bot: TelegramClient) {}
+
+  async notify(chatId: number | string, text: string) {
+    await this.bot.sendMessage(chatId, text);
+  }
+}
+```
+
+Requiere `TELEGRAM_BOT_TOKEN` en el entorno — falla explícito al arrancar si falta, igual que
+`PgModule`/`SupabaseModule`. `TelegramModule` solo expone el cliente de **salida** (`Telegram`, la
+clase de `telegraf` para llamar directo a la Bot API): no hay polling, no hay webhook, no hay manejo
+de updates entrantes — es a propósito, este paquete no enruta mensajes recibidos. Importa el tipo del
+cliente como `Telegram as TelegramClient` si tipas tu propia inyección — `telegraf` exporta una clase
+llamada `Telegram`, que choca de nombre con el concepto genérico "Telegram" en tu propio código.
+
+### `whatsapp` — cliente de salida sobre la Cloud API de Meta
+
+```ts
+import { Module } from '@nestjs/common';
+import { WhatsAppModule } from '@miguelmorales13/nestkit/whatsapp';
+
+@Module({ imports: [WhatsAppModule] })
+export class AppModule {}
+```
+
+```ts
+import { Inject, Injectable } from '@nestjs/common';
+import { WHATSAPP_CLIENT, WhatsAppClient } from '@miguelmorales13/nestkit/whatsapp';
+
+@Injectable()
+export class NotificationsService {
+  constructor(@Inject(WHATSAPP_CLIENT) private readonly whatsapp: WhatsAppClient) {}
+
+  async notify(to: string, body: string) {
+    await this.whatsapp.sendTextMessage(to, body);
+  }
+}
+```
+
+Requiere `WHATSAPP_ACCESS_TOKEN` y `WHATSAPP_PHONE_NUMBER_ID`; `WHATSAPP_API_VERSION` es opcional
+(default `v21.0`). No hay dependencia npm de por medio — Meta no publica un SDK oficial de Node
+razonable para la Cloud API, que de todos modos es un REST plano, así que `WhatsAppClient` usa el
+`fetch` global de Node (18+) directo. Solo manda mensajes de texto (`sendTextMessage`) — sin
+templates, sin media, sin manejo de mensajes entrantes.
+
+### `stripe` — cliente de la SDK oficial
+
+```ts
+import { Module } from '@nestjs/common';
+import { StripeModule } from '@miguelmorales13/nestkit/stripe';
+
+@Module({ imports: [StripeModule] })
+export class AppModule {}
+```
+
+```ts
+import { Inject, Injectable } from '@nestjs/common';
+import { STRIPE_CLIENT } from '@miguelmorales13/nestkit/stripe';
+import type Stripe from 'stripe';
+
+@Injectable()
+export class BillingService {
+  constructor(@Inject(STRIPE_CLIENT) private readonly stripe: Stripe) {}
+
+  async createCustomer(email: string) {
+    return this.stripe.customers.create({ email });
+  }
+}
+```
+
+Requiere `STRIPE_SECRET_KEY`. `STRIPE_API_VERSION` es opcional — si no la fijas, la SDK usa su propia
+versión pineada por default (no la fuerces a mano salvo que sepas exactamente por qué). Como
+Postgres/Supabase, solo expone el cliente crudo por DI — no envuelve `Stripe` en tipos propios de
+`nestkit`, así que tipa tu inyección directo contra `Stripe` de la librería `stripe`.
+
+#### Webhooks de Stripe
+
+> **Requisito obligatorio**: tu `main.ts` tiene que crear la app con
+> `NestFactory.create(AppModule, { rawBody: true })`. La verificación de firma de Stripe necesita los
+> bytes crudos del request tal cual llegaron — `applyNestKitDefaults` corre **después** de crear la
+> app y no puede habilitar `rawBody` en retrospectiva. Sin esto, el controller lanza un error
+> explícito en cuanto le llega un webhook, en vez de fallar silencioso.
+
+```ts
+// main.ts
+const app = await NestFactory.create(AppModule, { rawBody: true });
+```
+
+```ts
+import { Module } from '@nestjs/common';
+import { createStripeWebhookController } from '@miguelmorales13/nestkit/stripe';
+
+class StripeWebhookController extends createStripeWebhookController({
+  handlers: {
+    'checkout.session.completed': async (event) => {
+      // event.data.object es el Checkout Session
+    },
+    'customer.subscription.updated': async (event) => {
+      // actualiza el plan del tenant en tu propia DB
+    },
+  },
+}) {}
+
+@Module({ controllers: [StripeWebhookController] })
+export class BillingModule {}
+```
+
+Requiere `STRIPE_WEBHOOK_SECRET` además de `STRIPE_SECRET_KEY`. Los tipos de evento sin handler
+registrado se acusan recibo (`{ received: true }`) y se ignoran — Stripe espera un 200 rápido,
+no que manejes cada tipo de evento que te manda.
+
+### `auth` — flujo completo de registro/login, para empresa o para persona sola
+
+Mismo espíritu que `crud`: `nestkit` define el puerto (`AuthUserPort`) y la orquestación
+(`BaseAuthService`, `createAuthController`), vos traés tu propia entidad/persistencia. A diferencia
+de los demás módulos, **no hay `Module` que importar** — son clases y guards planos que se usan
+directo, sin registro en el contenedor de DI.
+
+```ts
+// user.repository.ts
+import { Injectable } from '@nestjs/common';
+import type { AuthUser, AuthUserPort } from '@miguelmorales13/nestkit/auth';
+
+interface User extends AuthUser {}
+
+@Injectable()
+export class UserRepository implements AuthUserPort<User> {
+  async findByEmail(email: string): Promise<User | null> { /* ... */ return null; }
+  async findById(id: string): Promise<User | null> { /* ... */ return null; }
+  async create(data: { email: string; passwordHash: string; tenantId?: string; roles: string[] }): Promise<User> {
+    /* insertar y devolver el user creado */
+    throw new Error('not implemented');
+  }
+}
+```
+
+```ts
+// auth.module.ts
+import { Module } from '@nestjs/common';
+import { BaseAuthService, createAuthController } from '@miguelmorales13/nestkit/auth';
+import { UserRepository } from './user.repository';
+
+const AUTH_SERVICE = 'AUTH_SERVICE';
+
+class AuthController extends createAuthController(AUTH_SERVICE as any) {}
+
+@Module({
+  controllers: [AuthController],
+  providers: [
+    UserRepository,
+    { provide: AUTH_SERVICE, useFactory: (users: UserRepository) => new BaseAuthService(users), inject: [UserRepository] },
+  ],
+})
+export class AuthModule {}
+```
+
+> En la práctica, igual que con `crud`, usa una subclase concreta de `BaseAuthService` como
+> provider/token para que TypeScript infiera los tipos sin castear.
+
+Esto ya te da `POST /auth/register`, `POST /auth/login`, `POST /auth/refresh` funcionando. Para que
+sirva **tanto para una empresa como para una persona que se registra sola**, `tenantId` es opcional
+en todo el flujo: mandalo en el body de `register` si el usuario pertenece a una empresa, omitilo
+para una cuenta individual — queda como `undefined` en el JWT y en la entidad, nada más se rompe.
+
+**Proteger rutas** — el orden de los guards importa, `JwtAuthGuard` tiene que ir primero (es el que
+puebla `request.user`):
+
+```ts
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import {
+  JwtAuthGuard,
+  RolesGuard,
+  Roles,
+  RequireTenantGuard,
+  CurrentUser,
+  CurrentTenant,
+  type AuthenticatedUser,
+} from '@miguelmorales13/nestkit/auth';
+
+@Controller('widgets')
+@UseGuards(JwtAuthGuard)
+export class WidgetsController {
+  @Get('me')
+  me(@CurrentUser() user: AuthenticatedUser) {
+    return user;
+  }
+
+  @Get('admin-only')
+  @UseGuards(RolesGuard)
+  @Roles('admin')
+  adminOnly() { /* ... */ }
+
+  @Get('company-only')
+  @UseGuards(RequireTenantGuard)
+  companyOnly(@CurrentTenant() tenantId: string) { /* tenantId nunca es undefined acá */ }
+}
+```
+
+`RequireTenantGuard` es el opt-in para endpoints que **sí** deben ser exclusivos de cuentas de
+empresa — sin él, cualquier ruta protegida por `JwtAuthGuard` funciona igual de bien para una cuenta
+individual (`tenantId: undefined`) que para una de empresa.
+
+**Integración con `crud`** — `tenantIdExtractor` de `createCrudController` lee directo del JWT que
+`JwtAuthGuard` ya decodificó:
+
+```ts
+class WidgetsController extends createCrudController(WIDGETS_SERVICE as any, {
+  path: 'widgets',
+  tenantIdExtractor: (req) => (req as { user?: AuthenticatedUser }).user?.tenantId,
+}) {}
+```
+
+Requiere `JWT_ACCESS_SECRET` y `JWT_REFRESH_SECRET`; `JWT_ACCESS_EXPIRES_IN` (default `15m`) y
+`JWT_REFRESH_EXPIRES_IN` (default `30d`) son opcionales. Los passwords se hashean con `bcryptjs`
+(oculto — no es peer dependency, no lo importás vos); los tokens usan `jsonwebtoken` por debajo,
+también oculto. `login()` devuelve el mismo mensaje de error para "no existe el usuario" y
+"contraseña incorrecta" — evita que alguien pueda usar el endpoint para enumerar emails registrados.
+
+`register()` siempre asigna `roles: ['user']` — no hay forma de pasar otro rol inicial desde el
+body (a propósito: dejarlo abierto desde el request sería que cualquiera se autoasigne `admin`). Si
+necesitás otra lógica de roles al alta (ej. el primer usuario de un tenant nuevo es `owner`), extendé
+`BaseAuthService` y sobreescribí `register()`, o llamá `users.create()` directo con los roles que
+quieras desde tu propio controller.
+
+### `email/resend` y `email/nodemailer` — dos transportes, elegís uno por proyecto
+
+Mismo patrón que `database/postgres` vs `database/supabase`: dos módulos independientes, no una
+abstracción unificada — importás el que le convenga al proyecto.
+
+```ts
+import { Module } from '@nestjs/common';
+import { ResendModule } from '@miguelmorales13/nestkit/email/resend';
+
+@Module({ imports: [ResendModule] })
+export class AppModule {}
+```
+
+```ts
+import { Inject, Injectable } from '@nestjs/common';
+import { RESEND_CLIENT } from '@miguelmorales13/nestkit/email/resend';
+import type { Resend } from 'resend';
+
+@Injectable()
+export class NotificationsService {
+  constructor(@Inject(RESEND_CLIENT) private readonly resend: Resend) {}
+
+  async notify(to: string, subject: string, html: string) {
+    await this.resend.emails.send({ from: 'noreply@tudominio.com', to, subject, html });
+  }
+}
+```
+
+Requiere `RESEND_API_KEY`. Elegí Resend para proyectos nuevos: una sola API key, SDK oficial liviano.
+
+```ts
+import { Module } from '@nestjs/common';
+import { NodemailerModule } from '@miguelmorales13/nestkit/email/nodemailer';
+
+@Module({ imports: [NodemailerModule] })
+export class AppModule {}
+```
+
+```ts
+import { Inject, Injectable } from '@nestjs/common';
+import { NODEMAILER_TRANSPORT } from '@miguelmorales13/nestkit/email/nodemailer';
+import type { Transporter } from 'nodemailer';
+
+@Injectable()
+export class NotificationsService {
+  constructor(@Inject(NODEMAILER_TRANSPORT) private readonly mailer: Transporter) {}
+
+  async notify(to: string, subject: string, html: string) {
+    await this.mailer.sendMail({ from: 'noreply@tudominio.com', to, subject, html });
+  }
+}
+```
+
+Requiere `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`; `SMTP_SECURE` es opcional (`'true'`
+para forzar TLS directo). Elegí Nodemailer cuando ya tenés un proveedor SMTP propio (Gmail, SES,
+Mailgun, tu propio servidor) en vez de sumar otra cuenta de terceros.
+
 ## Subpaths disponibles
 
 | Subpath | Qué trae |
@@ -400,12 +698,18 @@ original.
 | `@miguelmorales13/nestkit/database/postgres` | `PgModule`, `PG_POOL`, `withTenantScope` |
 | `@miguelmorales13/nestkit/database/supabase` | `SupabaseModule`, `SUPABASE_ANON_CLIENT`, `SUPABASE_SERVICE_ROLE_CLIENT` |
 | `@miguelmorales13/nestkit/database/mongo` | Solo el contrato `MongoRepositoryPort` — sin implementación |
+| `@miguelmorales13/nestkit/telegram` | `TelegramModule`, `TELEGRAM_BOT` |
+| `@miguelmorales13/nestkit/whatsapp` | `WhatsAppModule`, `WHATSAPP_CLIENT`, `WhatsAppClient` |
+| `@miguelmorales13/nestkit/stripe` | `StripeModule`, `STRIPE_CLIENT`, `createStripeWebhookController` |
+| `@miguelmorales13/nestkit/auth` | `AuthUserPort`, `BaseAuthService`, `createAuthController`, `TokenService`, `JwtAuthGuard`, `RolesGuard`, `RequireTenantGuard`, `CurrentUser`, `CurrentTenant`, `Roles` |
+| `@miguelmorales13/nestkit/email/resend` | `ResendModule`, `RESEND_CLIENT` |
+| `@miguelmorales13/nestkit/email/nodemailer` | `NodemailerModule`, `NODEMAILER_TRANSPORT` |
 | `@miguelmorales13/nestkit/i18n` | `I18nModule` (wrapper de `nestjs-i18n`), `translateOr` |
 | `@miguelmorales13/nestkit/bootstrap` | `applyNestKitDefaults` |
 
 ## Estado del paquete
 
-`0.1.0`, no publicado en npm todavía (repo privado, se prueba localmente con `bun link` antes de
+`0.3.0`, no publicado en npm todavía (repo privado, se prueba localmente con `bun link` antes de
 publicar). Sin adaptador Mongo real. Sin tests unitarios propios — es un paquete nuevo sin
 consumidor productivo todavía; la primera integración real (ej. en `hr-pymes-saas`) es la que va a
 ejercitar el código de verdad.

package/dist/auth/auth-user.entity.d.ts

@@ -0,0 +1,8 @@
+import type { BaseEntity } from '../entities/base.entity.js';
+export interface AuthUser extends BaseEntity {
+    email: string;
+    passwordHash: string;
+    /** Absent for an individual/solo account — present for a company-owned user. */
+    tenantId?: string;
+    roles: string[];
+}

package/dist/auth/auth-user.port.d.ts

@@ -0,0 +1,16 @@
+import type { AuthUser } from './auth-user.entity.js';
+/**
+ * Persistence port for the Auth module — parallel to crud's Repository<T>.
+ * The consumer implements this against their own storage; nestkit only
+ * orchestrates hashing/token issuance on top of it.
+ */
+export interface AuthUserPort<U extends AuthUser = AuthUser> {
+    findByEmail(email: string): Promise<U | null>;
+    findById(id: string): Promise<U | null>;
+    create(data: {
+        email: string;
+        passwordHash: string;
+        tenantId?: string;
+        roles: string[];
+    }): Promise<U>;
+}

package/dist/auth/auth.controller.d.ts

@@ -0,0 +1,25 @@
+import { type Type } from '@nestjs/common';
+import { LoginDto, RefreshDto, RegisterDto } from './auth.dto.js';
+import type { AuthUser } from './auth-user.entity.js';
+import type { AuthTokens, BaseAuthService } from './auth.service.js';
+export interface CreateAuthControllerOptions {
+    /** Route prefix for the generated controller. Defaults to 'auth'. */
+    path?: string;
+}
+/**
+ * Mixin factory (function returning a class) that wires up register/login/
+ * refresh to a BaseAuthService — composition, not forced inheritance, same
+ * shape as crud's createCrudController.
+ *
+ * Usage:
+ *   class AuthController extends createAuthController(AUTH_SERVICE as any) {}
+ */
+export declare function createAuthController<U extends AuthUser>(serviceToken: Type<BaseAuthService<U>>, options?: CreateAuthControllerOptions): Type<{
+    register(body: RegisterDto): Promise<{
+        user: U;
+    } & AuthTokens>;
+    login(body: LoginDto): Promise<{
+        user: U;
+    } & AuthTokens>;
+    refresh(body: RefreshDto): Promise<AuthTokens>;
+}>;

package/dist/auth/auth.dto.d.ts

@@ -0,0 +1,13 @@
+export declare class RegisterDto {
+    email: string;
+    password: string;
+    /** Omit for an individual/solo signup — provide for a company-owned user. */
+    tenantId?: string;
+}
+export declare class LoginDto {
+    email: string;
+    password: string;
+}
+export declare class RefreshDto {
+    refreshToken: string;
+}

package/dist/auth/auth.service.d.ts

@@ -0,0 +1,24 @@
+import { TokenService } from './token.service.js';
+import type { AuthUser } from './auth-user.entity.js';
+import type { AuthUserPort } from './auth-user.port.js';
+export interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+}
+export declare class BaseAuthService<U extends AuthUser> {
+    protected readonly users: AuthUserPort<U>;
+    protected readonly tokens: TokenService;
+    constructor(users: AuthUserPort<U>, tokens?: TokenService);
+    register(data: {
+        email: string;
+        password: string;
+        tenantId?: string;
+    }): Promise<{
+        user: U;
+    } & AuthTokens>;
+    login(email: string, password: string): Promise<{
+        user: U;
+    } & AuthTokens>;
+    refresh(refreshToken: string): Promise<AuthTokens>;
+    private issueTokens;
+}

package/dist/auth/authenticated-user.d.ts

@@ -0,0 +1,7 @@
+/** Decoded JWT payload shape, attached to `request.user` by JwtAuthGuard. */
+export interface AuthenticatedUser {
+    sub: string;
+    email: string;
+    tenantId?: string;
+    roles: string[];
+}

package/dist/auth/current-tenant.decorator.d.ts

@@ -0,0 +1,2 @@
+/** Returns `undefined` for an individual/solo account — no tenantId to read. */
+export declare const CurrentTenant: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/auth/current-user.decorator.d.ts

@@ -0,0 +1 @@
+export declare const CurrentUser: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/auth/hash.util.d.ts

@@ -0,0 +1,2 @@
+export declare function hashPassword(plain: string): Promise<string>;
+export declare function verifyPassword(plain: string, passwordHash: string): Promise<boolean>;