npm package: @hegoatek/core
Description: HegoaTek Core - Reusable NestJS modules for authentication, email, storage, and more
Author: HegoaTek
Latest version: 1.2.1

# @hegoatek/core

A collection of reusable, production-ready NestJS modules designed for the HegoaTek ecosystem. This library implements the "Factory Pattern" to dynamically provide implementations for authentication, storage, and email based on configuration.

## Installation

```bash
npm install @hegoatek/core
```

You will also need to install the necessary peer dependencies depending on which modules you use (NestJS, Prisma, AWS SDK, etc.).

## Modules Overview

This library is organized into several sub-modules that can be imported individually or together.

### 1. Authentication (`AuthCoreModule`)

Provides a complete authentication system with support for multiple providers.

**Supported Providers:**
- `custom`: JWT + bcrypt (Local)
- `supabase`: Supabase Auth Integration

**Usage:**

The module requires a Prisma module/service to be injected for user persistence.

```typescript
import { Module } from '@nestjs/common';
import { AuthCoreModule } from '@hegoatek/core/auth';
import { PrismaModule } from './prisma/prisma.module';
import { PrismaService } from './prisma/prisma.service';

@Module({
  imports: [
    AuthCoreModule.forRoot({
      prismaModule: PrismaModule,
      prismaService: PrismaService,
      // Config is automatically loaded from environment variables
    }),
  ],
})
export class AppModule {}
```

**Environment Variables:**

```bash
AUTH_PROVIDER=custom # or 'supabase'
JWT_SECRET=super-secret
JWT_EXPIRATION_SECONDS=86400
```

**Prisma Service Requirement:**

Your `PrismaService` must implement the `PrismaServiceInterface` expected by the auth provider:

```typescript
interface PrismaServiceInterface {
  user: {
    findUnique: (args: any) => Promise<User | null>;
    create: (args: any) => Promise<User>;
    // ... other methods
  };
}
```

### 2. Storage (`StorageModule`)

Abstracts file storage operations, allowing you to switch between local storage and cloud object storage without changing your application code.

**Supported Providers:**
- `local`: Stores files in a local directory (great for dev)
- `cloudflare-r2`: S3-compatible storage for Cloudflare R2 (or AWS S3)

**Usage:**

```typescript
import { Module } from '@nestjs/common';
import { StorageModule } from '@hegoatek/core/storage';

@Module({
  imports: [
    StorageModule.forRootAsync(), // Configuration loaded from env
  ],
})
export class AppModule {}
```

**Service Usage:**

```typescript
import { Injectable, Inject } from '@nestjs/common';
import { StorageService } from '@hegoatek/core/storage';

@Injectable()
export class AppService {
  constructor(private readonly storageService: StorageService) {}

  async uploadFile(file: Express.Multer.File) {
    const url = await this.storageService.upload(file.buffer, 'uploads/my-file.png');
    return url;
  }
}
```

**Environment Variables:**

```bash
STORAGE_PROVIDER=cloudflare-r2 # or 'local'

# If using Cloudflare R2 / S3
R2_ACCOUNT_ID=xxx
R2_ACCESS_KEY_ID=xxx
R2_SECRET_ACCESS_KEY=xxx
R2_BUCKET_NAME=xxx
```

### 3. Mail (`MailModule`)

Email sending wrapper, currently optimized for Resend.

**Usage:**

```typescript
import { Module } from '@nestjs/common';
import { MailModule } from '@hegoatek/core/mail';

@Module({
  imports: [MailModule],
})
export class AppModule {}
```

**Environment Variables:**

```bash
RESEND_API_KEY=re_123456
MAIL_FROM=noreply@yourdomain.com
```

### 4. Common Utilities (`CommonModule`)

Includes shared NestJS infrastructure components:

- `HttpExceptionFilter`: Standardized error responses
- `TransformInterceptor`: Standardized success responses wrapping
- `ApiResponse` interfaces

```typescript
import { Module } from '@nestjs/common';
import { APP_FILTER, APP_INTERCEPTOR } from '@nestjs/core';
import { HttpExceptionFilter, TransformInterceptor } from '@hegoatek/core/common';

@Module({
  providers: [
    { provide: APP_FILTER, useClass: HttpExceptionFilter },
    { provide: APP_INTERCEPTOR, useClass: TransformInterceptor },
  ],
})
export class AppModule {}
```

### 5. Configuration (`HegoatekConfigModule`)

An opinionated wrapper around `@nestjs/config` that loads and validates environment variables specific to the HegoaTek ecosystem.

## Architecture & Patterns

### Factory Pattern for Providers

Instead of hardcoding implementation details, this library uses a Factory Pattern. The `AUTH_PROVIDER` and `STORAGE_PROVIDER` symbols are used to inject the correct service implementation at runtime based on environment variables.

### Provider Injection Tokens

If you need to inject the underlying provider directly (though usually, you should use the wrapper services):

```typescript
import { AUTH_PROVIDER, STORAGE_PROVIDER } from '@hegoatek/core';
```

## Peer Dependencies

Ensure you have the following installed in your host application:

- `@nestjs/common`
- `@nestjs/core`
- `@nestjs/config`
- `@prisma/client` (if using Auth)
- `@aws-sdk/client-s3` (if using R2/S3 Storage)
- `resend` (if using Mail)

## License

MIT