@vritti/api-sdk 0.0.3 → 0.0.5

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _nestjs_common from '@nestjs/common';
-import { DynamicModule, OnModuleDestroy, OnModuleInit, CanActivate, ExecutionContext } from '@nestjs/common';
+import { DynamicModule, OnModuleDestroy, OnModuleInit, Logger, CanActivate, ExecutionContext, ExceptionFilter, ArgumentsHost } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { Reflector } from '@nestjs/core';
 import { JwtService } from '@nestjs/jwt';
@@ -376,6 +376,15 @@ declare class TenantDatabaseService implements OnModuleDestroy {
     /** Cleanup interval timer */
     private cleanupInterval?;
     constructor(options: DatabaseModuleOptions, tenantContext: TenantContextService);
+    /**
+     * Get the Prisma client for the current tenant's database.
+     * This returns the tenant-scoped database client.
+     *
+     * @returns Tenant-scoped database client instance
+     * @throws UnauthorizedException if tenant context not set
+     * @throws InternalServerErrorException if connection fails
+     */
+    get prismaClient(): any;
     /**
      * Get tenant-scoped database client for the current request/message
      *
@@ -392,7 +401,7 @@ declare class TenantDatabaseService implements OnModuleDestroy {
      * const dbClient = await tenantDatabase.getDbClient<PrismaClient>();
      * const users = await dbClient.user.findMany();
      */
-    getDbClient<T = any>(): Promise<T>;
+    private getDbClient;
     /**
      * Create a new database client for the given tenant
      */
@@ -488,14 +497,13 @@ declare class PrimaryDatabaseService implements OnModuleInit, OnModuleDestroy {
      */
     clearAllCaches(): void;
     /**
-     * Get primary database client for direct database access
-     *
-     * This is useful for platform admin operations (creating tenants, billing, etc.)
+     * Get the Prisma client for the primary database.
+     * This is a synchronous property that returns the initialized Prisma client.
      *
      * @returns Primary database client instance
      * @throws Error if primary database client is not initialized
      */
-    getPrimaryDbClient<T = any>(): T;
+    get prismaClient(): any;
     /**
      * Decrypt database credentials
      *
@@ -508,6 +516,503 @@ declare class PrimaryDatabaseService implements OnModuleInit, OnModuleDestroy {
     onModuleDestroy(): Promise<void>;
 }
 
+/**
+ * Abstract base repository for primary database operations.
+ * Provides common CRUD operations with automatic logging.
+ *
+ * @template TModel - The Prisma model type
+ * @template TCreateDTO - DTO type for create operations
+ * @template TUpdateDTO - DTO type for update operations
+ *
+ * @example
+ * ```typescript
+ * // Using the model delegate pattern (RECOMMENDED)
+ * // Type-safe, IDE autocomplete, refactor-friendly
+ * @Injectable()
+ * export class UserRepository extends PrimaryBaseRepository<
+ *   User,
+ *   CreateUserDto,
+ *   UpdateUserDto
+ * > {
+ *   constructor(database: PrimaryDatabaseService) {
+ *     super(database, (prisma) => prisma.user);  // ✅ Type-safe with autocomplete!
+ *   }
+ *
+ *   // Add custom methods as needed
+ *   async findByEmail(email: string): Promise<User | null> {
+ *     return this.model.findUnique({ where: { email } });
+ *   }
+ * }
+ *
+ * // Short syntax is also supported
+ * @Injectable()
+ * export class TenantRepository extends PrimaryBaseRepository<Tenant> {
+ *   constructor(database: PrimaryDatabaseService) {
+ *     super(database, (p) => p.tenant);  // ✅ Concise!
+ *   }
+ * }
+ *
+ * // Works with complex model names
+ * @Injectable()
+ * export class EmailVerificationRepository extends PrimaryBaseRepository<EmailVerification> {
+ *   constructor(database: PrimaryDatabaseService) {
+ *     super(database, (p) => p.emailVerification);  // ✅ Matches Prisma naming
+ *   }
+ * }
+ * ```
+ */
+declare abstract class PrimaryBaseRepository<TModel, TCreateDTO = any, TUpdateDTO = any> {
+    protected readonly database: PrimaryDatabaseService;
+    protected readonly logger: Logger;
+    private readonly modelGetter;
+    /**
+     * Lazy getter for Prisma client.
+     * Accesses the client from the database service only when needed,
+     * avoiding initialization timing issues with NestJS lifecycle.
+     */
+    protected get prisma(): any;
+    /**
+     * Lazy getter for the Prisma model delegate.
+     * Returns the specific model (e.g., prisma.user, prisma.tenant) for this repository.
+     */
+    protected get model(): any;
+    /**
+     * Create a new repository instance
+     *
+     * @param database - The primary database service
+     * @param getModel - Function that returns the Prisma model delegate from the client
+     *
+     * @example
+     * ```typescript
+     * // Standard usage with full parameter name
+     * constructor(database: PrimaryDatabaseService) {
+     *   super(database, (prisma) => prisma.user);
+     * }
+     *
+     * // Short syntax
+     * constructor(database: PrimaryDatabaseService) {
+     *   super(database, (p) => p.user);
+     * }
+     *
+     * // Complex model names
+     * constructor(database: PrimaryDatabaseService) {
+     *   super(database, (p) => p.emailVerification);
+     * }
+     * ```
+     */
+    constructor(database: PrimaryDatabaseService, getModel: (prisma: any) => any);
+    /**
+     * Create a new record
+     *
+     * @param data - The data to create the record with
+     * @returns Promise resolving to the created record
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepository.create({
+     *   email: 'user@example.com',
+     *   name: 'John Doe'
+     * });
+     * ```
+     */
+    create(data: TCreateDTO): Promise<TModel>;
+    /**
+     * Find a single record by ID
+     *
+     * @param id - The record ID
+     * @returns Promise resolving to the record or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepository.findById('user-id-123');
+     * ```
+     */
+    findById(id: string): Promise<TModel | null>;
+    /**
+     * Find a single record with custom where clause
+     *
+     * @param where - The where clause or findUnique args
+     * @returns Promise resolving to the record or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Simple where clause
+     * const user = await userRepository.findOne({ email: 'user@example.com' });
+     *
+     * // With include
+     * const user = await userRepository.findOne({
+     *   where: { email: 'user@example.com' },
+     *   include: { posts: true }
+     * });
+     * ```
+     */
+    findOne(where: any): Promise<TModel | null>;
+    /**
+     * Find multiple records
+     *
+     * @param args - Prisma findMany arguments (where, orderBy, take, skip, etc.)
+     * @returns Promise resolving to an array of records
+     *
+     * @example
+     * ```typescript
+     * // Find all users
+     * const users = await userRepository.findMany();
+     *
+     * // Find with filtering and pagination
+     * const users = await userRepository.findMany({
+     *   where: { status: 'ACTIVE' },
+     *   orderBy: { createdAt: 'desc' },
+     *   take: 10,
+     *   skip: 0
+     * });
+     * ```
+     */
+    findMany(args?: any): Promise<TModel[]>;
+    /**
+     * Update a record by ID
+     *
+     * @param id - The record ID
+     * @param data - The data to update
+     * @returns Promise resolving to the updated record
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepository.update('user-id-123', {
+     *   name: 'Jane Doe'
+     * });
+     * ```
+     */
+    update(id: string, data: TUpdateDTO): Promise<TModel>;
+    /**
+     * Update multiple records
+     *
+     * @param where - The where clause to match records
+     * @param data - The data to update
+     * @returns Promise resolving to the count of updated records
+     *
+     * @example
+     * ```typescript
+     * const result = await userRepository.updateMany(
+     *   { status: 'PENDING' },
+     *   { status: 'ACTIVE' }
+     * );
+     * console.log(`Updated ${result.count} users`);
+     * ```
+     */
+    updateMany(where: any, data: TUpdateDTO): Promise<{
+        count: number;
+    }>;
+    /**
+     * Delete a record by ID
+     *
+     * @param id - The record ID
+     * @returns Promise resolving to the deleted record
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepository.delete('user-id-123');
+     * ```
+     */
+    delete(id: string): Promise<TModel>;
+    /**
+     * Delete multiple records
+     *
+     * @param where - The where clause to match records
+     * @returns Promise resolving to the count of deleted records
+     *
+     * @example
+     * ```typescript
+     * const result = await userRepository.deleteMany({
+     *   status: 'INACTIVE',
+     *   createdAt: { lt: new Date('2020-01-01') }
+     * });
+     * console.log(`Deleted ${result.count} users`);
+     * ```
+     */
+    deleteMany(where: any): Promise<{
+        count: number;
+    }>;
+    /**
+     * Count records
+     *
+     * @param where - Optional where clause to filter records
+     * @returns Promise resolving to the count of records
+     *
+     * @example
+     * ```typescript
+     * // Count all users
+     * const total = await userRepository.count();
+     *
+     * // Count active users
+     * const activeCount = await userRepository.count({ status: 'ACTIVE' });
+     * ```
+     */
+    count(where?: any): Promise<number>;
+    /**
+     * Check if a record exists
+     *
+     * @param where - The where clause to match records
+     * @returns Promise resolving to true if at least one record exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const emailExists = await userRepository.exists({
+     *   email: 'user@example.com'
+     * });
+     * ```
+     */
+    exists(where: any): Promise<boolean>;
+}
+
+/**
+ * Abstract base repository for tenant-scoped database operations.
+ * All operations are automatically scoped to the current tenant.
+ *
+ * @template TModel - The Prisma model type
+ * @template TCreateDTO - DTO type for create operations
+ * @template TUpdateDTO - DTO type for update operations
+ *
+ * @example
+ * ```typescript
+ * // Using the model delegate pattern (RECOMMENDED)
+ * // Type-safe, IDE autocomplete, refactor-friendly
+ * @Injectable()
+ * export class ProductRepository extends TenantBaseRepository<
+ *   Product,
+ *   CreateProductDto,
+ *   UpdateProductDto
+ * > {
+ *   constructor(database: TenantDatabaseService) {
+ *     super(database, (prisma) => prisma.product);  // ✅ Type-safe with autocomplete!
+ *   }
+ *
+ *   // Add custom methods as needed
+ *   async findBySku(sku: string): Promise<Product | null> {
+ *     return this.model.findUnique({ where: { sku } });
+ *   }
+ * }
+ *
+ * // Short syntax is also supported
+ * @Injectable()
+ * export class OrderRepository extends TenantBaseRepository<Order> {
+ *   constructor(database: TenantDatabaseService) {
+ *     super(database, (p) => p.order);  // ✅ Concise!
+ *   }
+ * }
+ *
+ * // Works with complex model names
+ * @Injectable()
+ * export class InventoryItemRepository extends TenantBaseRepository<InventoryItem> {
+ *   constructor(database: TenantDatabaseService) {
+ *     super(database, (p) => p.inventoryItem);  // ✅ Matches Prisma naming
+ *   }
+ * }
+ * ```
+ */
+declare abstract class TenantBaseRepository<TModel, TCreateDTO = any, TUpdateDTO = any> {
+    protected readonly database: TenantDatabaseService;
+    protected readonly logger: Logger;
+    private readonly modelGetter;
+    /**
+     * Lazy getter for Prisma client.
+     * Accesses the client from the database service only when needed,
+     * avoiding initialization timing issues with NestJS lifecycle.
+     */
+    protected get prisma(): any;
+    /**
+     * Lazy getter for the Prisma model delegate.
+     * Returns the specific model (e.g., prisma.product, prisma.order) for this repository.
+     */
+    protected get model(): any;
+    /**
+     * Create a new repository instance
+     *
+     * @param database - The tenant database service
+     * @param getModel - Function that returns the Prisma model delegate from the client
+     *
+     * @example
+     * ```typescript
+     * // Standard usage with full parameter name
+     * constructor(database: TenantDatabaseService) {
+     *   super(database, (prisma) => prisma.product);
+     * }
+     *
+     * // Short syntax
+     * constructor(database: TenantDatabaseService) {
+     *   super(database, (p) => p.product);
+     * }
+     *
+     * // Complex model names
+     * constructor(database: TenantDatabaseService) {
+     *   super(database, (p) => p.inventoryItem);
+     * }
+     * ```
+     */
+    constructor(database: TenantDatabaseService, getModel: (prisma: any) => any);
+    /**
+     * Create a new record
+     *
+     * @param data - The data to create the record with
+     * @returns Promise resolving to the created record
+     *
+     * @example
+     * ```typescript
+     * const product = await productRepository.create({
+     *   name: 'Widget',
+     *   sku: 'WDG-001',
+     *   price: 9.99
+     * });
+     * ```
+     */
+    create(data: TCreateDTO): Promise<TModel>;
+    /**
+     * Find a single record by ID
+     *
+     * @param id - The record ID
+     * @returns Promise resolving to the record or null if not found
+     *
+     * @example
+     * ```typescript
+     * const product = await productRepository.findById('product-id-123');
+     * ```
+     */
+    findById(id: string): Promise<TModel | null>;
+    /**
+     * Find a single record with custom where clause
+     *
+     * @param where - The where clause or findUnique args
+     * @returns Promise resolving to the record or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Simple where clause
+     * const product = await productRepository.findOne({ sku: 'WDG-001' });
+     *
+     * // With include
+     * const product = await productRepository.findOne({
+     *   where: { sku: 'WDG-001' },
+     *   include: { category: true }
+     * });
+     * ```
+     */
+    findOne(where: any): Promise<TModel | null>;
+    /**
+     * Find multiple records
+     *
+     * @param args - Prisma findMany arguments (where, orderBy, take, skip, etc.)
+     * @returns Promise resolving to an array of records
+     *
+     * @example
+     * ```typescript
+     * // Find all products
+     * const products = await productRepository.findMany();
+     *
+     * // Find with filtering and pagination
+     * const products = await productRepository.findMany({
+     *   where: { status: 'ACTIVE' },
+     *   orderBy: { createdAt: 'desc' },
+     *   take: 10,
+     *   skip: 0
+     * });
+     * ```
+     */
+    findMany(args?: any): Promise<TModel[]>;
+    /**
+     * Update a record by ID
+     *
+     * @param id - The record ID
+     * @param data - The data to update
+     * @returns Promise resolving to the updated record
+     *
+     * @example
+     * ```typescript
+     * const product = await productRepository.update('product-id-123', {
+     *   price: 12.99
+     * });
+     * ```
+     */
+    update(id: string, data: TUpdateDTO): Promise<TModel>;
+    /**
+     * Update multiple records
+     *
+     * @param where - The where clause to match records
+     * @param data - The data to update
+     * @returns Promise resolving to the count of updated records
+     *
+     * @example
+     * ```typescript
+     * const result = await productRepository.updateMany(
+     *   { status: 'PENDING' },
+     *   { status: 'ACTIVE' }
+     * );
+     * console.log(`Updated ${result.count} products`);
+     * ```
+     */
+    updateMany(where: any, data: TUpdateDTO): Promise<{
+        count: number;
+    }>;
+    /**
+     * Delete a record by ID
+     *
+     * @param id - The record ID
+     * @returns Promise resolving to the deleted record
+     *
+     * @example
+     * ```typescript
+     * const product = await productRepository.delete('product-id-123');
+     * ```
+     */
+    delete(id: string): Promise<TModel>;
+    /**
+     * Delete multiple records
+     *
+     * @param where - The where clause to match records
+     * @returns Promise resolving to the count of deleted records
+     *
+     * @example
+     * ```typescript
+     * const result = await productRepository.deleteMany({
+     *   status: 'INACTIVE',
+     *   createdAt: { lt: new Date('2020-01-01') }
+     * });
+     * console.log(`Deleted ${result.count} products`);
+     * ```
+     */
+    deleteMany(where: any): Promise<{
+        count: number;
+    }>;
+    /**
+     * Count records
+     *
+     * @param where - Optional where clause to filter records
+     * @returns Promise resolving to the count of records
+     *
+     * @example
+     * ```typescript
+     * // Count all products
+     * const total = await productRepository.count();
+     *
+     * // Count active products
+     * const activeCount = await productRepository.count({ status: 'ACTIVE' });
+     * ```
+     */
+    count(where?: any): Promise<number>;
+    /**
+     * Check if a record exists
+     *
+     * @param where - The where clause to match records
+     * @returns Promise resolving to true if at least one record exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const skuExists = await productRepository.exists({
+     *   sku: 'WDG-001'
+     * });
+     * ```
+     */
+    exists(where: any): Promise<boolean>;
+}
+
 declare class RequestService {
     private readonly request;
     constructor(request: FastifyRequest);
@@ -753,4 +1258,71 @@ declare const Onboarding: () => _nestjs_common.CustomDecorator<string>;
  */
 declare const Public: () => _nestjs_common.CustomDecorator<string>;
 
-export { AuthConfigModule, DatabaseModule, type DatabaseModuleOptions, Onboarding, PrimaryDatabaseService, type PrimaryDbConfig, Public, Tenant, TenantContextService, TenantDatabaseService, type TenantInfo, VrittiAuthGuard };
+/**
+ * HTTP Module
+ *
+ * Provides HTTP utilities including:
+ * - CSRF Guard for request protection
+ * - HTTP Exception Filter for standardized error responses
+ *
+ * Usage:
+ * Import this module to access HTTP guards and filters.
+ * Guards and filters are registered globally in the main application.
+ */
+declare class HttpModule {
+}
+
+/**
+ * CSRF Guard
+ *
+ * Global guard that automatically protects all state-changing requests (POST, PUT, PATCH, DELETE)
+ * from CSRF attacks using Fastify's csrf-protection plugin.
+ *
+ * Flow:
+ * 1. Skip safe methods (GET, HEAD, OPTIONS)
+ * 2. Skip endpoints marked with @Public()
+ * 3. Validate CSRF token for all other requests
+ *
+ * Token Sources (in priority order by @fastify/csrf-protection):
+ * 1. req.headers['csrf-token']
+ * 2. req.headers['xsrf-token']
+ * 3. req.headers['x-csrf-token']
+ * 4. req.headers['x-xsrf-token']
+ * 5. req.body._csrf
+ *
+ * This guard should be registered globally in main.ts after CSRF plugin registration.
+ */
+declare class CsrfGuard implements CanActivate {
+    private reflector;
+    private readonly logger;
+    constructor(reflector: Reflector);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+
+/**
+ * Global HTTP Exception Filter
+ *
+ * Standardizes all error responses in the format:
+ * {
+ *   errors: [{ field: string, message: string }],
+ *   message?: string,
+ *   statusCode: number,
+ *   timestamp: string,
+ *   path: string
+ * }
+ *
+ * Handles:
+ * - Validation errors (class-validator) - Converts to field-specific errors
+ * - HTTP exceptions - Maps to standardized format
+ * - Unknown errors - Returns generic 500 error
+ */
+declare class HttpExceptionFilter implements ExceptionFilter {
+    private readonly logger;
+    catch(exception: unknown, host: ArgumentsHost): void;
+    /**
+     * Parse class-validator error messages into field-specific errors
+     */
+    private parseValidationErrors;
+}
+
+export { AuthConfigModule, CsrfGuard, DatabaseModule, type DatabaseModuleOptions, HttpExceptionFilter, HttpModule, Onboarding, PrimaryBaseRepository, PrimaryDatabaseService, type PrimaryDbConfig, Public, Tenant, TenantBaseRepository, TenantContextService, TenantDatabaseService, type TenantInfo, VrittiAuthGuard };