appcore/README.md

# AppCore

A comprehensive, production-ready Go utility library providing core functionality for building modern web applications.

[![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go)](https://go.dev/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

AppCore is a modular Go library that provides essential building blocks for web applications, with a focus on security, developer experience, and production reliability. The library offers reusable packages for common tasks including cryptography, email handling, JWT authentication, validation, and HTTP utilities.

## Features

- **Security-First Design**: Modern cryptography (ED25519, AES-GCM, Argon2id) following OWASP recommendations
- **Type Safety**: Extensive use of Go generics and strong typing throughout
- **Production Ready**: Comprehensive error handling and proper resource cleanup
- **Developer Experience**: Convenient helper functions with consistent naming conventions
- **Cross-Platform Support**: Works seamlessly across macOS, Linux, and Windows
- **Modular Architecture**: Import only the packages you need

## Installation

```bash
go get code.patial.tech/go/appcore
```

## Packages

### Security & Cryptography (`crypto`)

Password hashing, encryption, digital signatures, and secure random generation.

```go
import "code.patial.tech/go/appcore/crypto"

// Password hashing (Argon2id - OWASP compliant)
hash, err := crypto.PasswordHash("mypassword")
valid := crypto.ComparePasswordHash("mypassword", hash)

// AES-GCM encryption
key := crypto.NewEncryptionKey(32)
encrypted, err := crypto.Encrypt([]byte("data"), key)
decrypted, err := crypto.Decrypt(encrypted, key)

// ED25519 key management
privateKey, publicKey, err := crypto.NewPersistedED25519("./keys")

// Secure random generation
randomBytes, err := crypto.RandomBytes(32)
randomHex := crypto.RandomBytesHex(16)
```

**Key Functions**: `MD5()`, `SHA256()`, `PasswordHash()`, `ComparePasswordHash()`, `NewEncryptionKey()`, `Encrypt()`, `Decrypt()`, `NewPersistedED25519()`, `ParseEdPrivateKey()`, `ParseEdPublicKey()`, `RandomBytes()`, `RandomBytesHex()`

### JWT Authentication (`jwt`)

JWT token signing and parsing with support for EdDSA and HS256 algorithms.

```go
import "code.patial.tech/go/appcore/jwt"

// EdDSA (recommended)
token, err := jwt.SignEdDSA(privateKey, "issuer", "subject", time.Hour, extraClaims)
claims, err := jwt.ParseEdDSA(token, publicKey, "issuer")

// HS256
token, err := jwt.SignHS256(secret, "issuer", "subject", time.Hour, extraClaims)
claims, err := jwt.ParseHS256(token, secret, "issuer")
```

**Key Functions**: `Sign()`, `Parse()`, `SignEdDSA()`, `ParseEdDSA()`, `SignHS256()`, `ParseHS256()`

### Email Handling (`email`)

Email construction and delivery with SMTP support and development mode.

```go
import "code.patial.tech/go/appcore/email"

msg := &email.Message{
    From:    "sender@example.com",
    To:      []string{"recipient@example.com"},
    Subject: "Hello",
    Body:    "<h1>Hello World</h1>",
}

// SMTP transport
transport := email.NewSMTPTransport("smtp.example.com", 587, "user", "pass")
err := msg.Send(transport)

// Development mode (opens in browser)
transport := email.NewDumpToTempTransport()
err := msg.Send(transport)
```

**Key Types**: `Message`, `Transport`, `SMTPTransport`, `DumpToTempTransport`

### Data Validation (`validate`)

Struct and map validation using go-playground/validator.

```go
import "code.patial.tech/go/appcore/validate"

type User struct {
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age" validate:"gte=0,lte=130"`
}

user := &User{Email: "test@example.com", Age: 25}
err := validate.Struct(user) // Returns validation errors with JSON field names
```

**Key Functions**: `Struct()`, `Map()`, `RegisterAlias()`, `RegisterValidation()`

### Environment Configuration (`dotenv`)

Environment file parsing with variable expansion and struct assignment.

```go
import "code.patial.tech/go/appcore/dotenv"

// Read .env file
env, err := dotenv.Read(".env")

// Assign to struct
type Config struct {
    Port int    `env:"PORT"`
    Host string `env:"HOST,HOSTNAME"` // Supports fallback tags
}
cfg := &Config{}
err := dotenv.Assign(env, cfg)

// Write .env file
err := dotenv.Write(env, ".env")
```

**Key Functions**: `Read()`, `LoadFile()`, `Write()`, `Assign()`

### HTTP Request Utilities (`request`)

Request parsing, validation, and pagination helpers.

```go
import "code.patial.tech/go/appcore/request"

// Parse and validate JSON payload
type CreateUserRequest struct {
    Email string `json:"email" validate:"required,email"`
}
var req CreateUserRequest
err := request.PayloadWithValidate(r, &req)

// Get pagination parameters
pager := request.GetPager(r.URL.Query(), 50) // default page size 50
```

**Key Functions**: `Payload()`, `PayloadWithValidate()`, `PayloadMap()`, `FormField()`, `GetPager()`

### HTTP Response Utilities (`response`)

Standardized JSON response formatting.

```go
import "code.patial.tech/go/appcore/response"

// Success responses
response.Ok(w, data)
response.Paged(w, data, pager, totalRecords)

// Error responses
response.BadRequest(w, "Invalid input")
response.InternalServerError(w, err)
response.NotAuthorized(w, "Invalid credentials")
response.Forbidden(w, "Access denied")
response.SessionExpired(w)
```

**Key Functions**: `Ok()`, `Paged()`, `BadRequest()`, `InternalServerError()`, `SessionExpired()`, `NotAuthorized()`, `Forbidden()`

### Pointer Utilities (`ptr`)

Safe reference and dereference operations with generic support.

```go
import "code.patial.tech/go/appcore/ptr"

// Generic reference/dereference
strPtr := ptr.Ref("hello")
str := ptr.Deref(strPtr, "default")

// Type-specific helpers
boolPtr := ptr.Bool(true)
numPtr := ptr.Number(42)
strPtr := ptr.Str("test")

// Safe getters with defaults
value := ptr.GetBool(boolPtr, false)
num := ptr.GetNumber(numPtr, 0)
str := ptr.GetStr(strPtr, "")
```

**Key Functions**: `Ref()`, `Deref()`, `Bool()`, `GetBool()`, `Str()`, `GetStr()`, `StrTrim()`, `Number()`, `GetNumber()`

### Unique ID Generation (`uid`)

UUID v7 and Sqids-based ID generation.

```go
import "code.patial.tech/go/appcore/uid"

// UUID v7 (time-based)
id := uid.NewUUID()

// Sqids (URL-friendly encoding)
encoded := uid.Encode(123, 456)
numbers, err := uid.Decode(encoded)
```

**Key Functions**: `NewUUID()`, `Encode()`, `Decode()`

### Date/Time Utilities (`date`)

Date parsing, arithmetic, and boundary calculations.

```go
import "code.patial.tech/go/appcore/date"

// Parse ISO date
t, err := date.ParseISODate("2024-01-15")

// Calculate working days
days := date.CountWorkingDays(startDate, endDate)

// Date boundaries
startOfDay := date.StartOfDay(now)
endOfMonth := date.EndOfMonth(now)
startOfWeek := date.StartOfWeek(now)

// Date arithmetic
lastWeek := date.LastWeek()
lastMonth := date.LastMonth()
threeMonthsAgo := date.SubtractMonths(now, 3)
```

**Key Functions**: `ParseISODate()`, `CountWorkingDays()`, `StartOfDay()`, `EndOfDay()`, `StartOfMonth()`, `EndOfMonth()`, `StartOfWeek()`, `EndOfWeek()`, `StartOfYear()`, `EndOfYear()`, `LastWeek()`, `LastMonth()`, `SubtractMonths()`, `SubtractDays()`, `SubtractAYear()`

### Compression (`gz`)

Gzip compression and decompression.

```go
import "code.patial.tech/go/appcore/gz"

// Compress data
compressed, err := gz.Zip([]byte("data"))

// Decompress data
decompressed, err := gz.UnZip(compressed)
```

**Key Functions**: `Zip()`, `UnZip()`

### Additional Utilities

- **`open`**: Cross-platform file/URI opening (`WithDefaultApp()`, `App()`)
- **`structs`**: Reflection utilities (`Map()` - converts structs to maps)
- **`mime`**: MIME type lookups from file extensions

## Dependencies

- `github.com/go-playground/validator/v10` - Data validation
- `github.com/golang-jwt/jwt/v5` - JWT handling
- `github.com/google/uuid` - UUID generation
- `github.com/sqids/sqids-go` - URL-friendly ID encoding
- `golang.org/x/crypto` - Cryptographic primitives

## Use Cases

AppCore is particularly well-suited for:

- Building secure web applications and REST APIs
- Standardizing authentication/authorization patterns
- Email delivery systems
- Configuration management
- API response formatting
- Data validation and sanitization

## Security

- **Password Hashing**: Uses Argon2id with OWASP-recommended parameters (m=19456, t=2, p=1)
- **Encryption**: AES-GCM authenticated encryption
- **JWT**: Supports EdDSA (recommended) and HS256 algorithms
- **Random Generation**: Cryptographically secure random bytes

## License

MIT License - see [LICENSE](LICENSE) file for details.

Copyright 2024/2025 Patial Tech (Ankit Patial).

## Contributing

Contributions are welcome! Please ensure:
- Code follows Go best practices and project conventions
- All tests pass (`go test ./...`)
- New features include appropriate documentation
- Security-sensitive code is reviewed carefully

## Support

For issues, questions, or feature requests, please open an issue on the project repository.