# Project Name

One-line description of what this project does.

## Features

- Key feature 1
- Key feature 2
- Key feature 3

## Installation

    npm install project-name

## Quick Start

    const project = require('project-name');
    project.doSomething();

## Documentation

See [full documentation](link) for detailed usage.

## Development

    npm install
    npm test
    npm run build

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT

# ADR-001: Use Event Sourcing for Audit Trail

**Status:** Accepted

**Date:** 2024-01-15

**Context:**
We need to maintain a complete audit trail of all changes to financial records
for regulatory compliance. The current update-in-place approach loses historical
state.

**Decision:**
Implement event sourcing pattern where all state changes are stored as immutable
events. Current state is derived by replaying events.

**Consequences:**

Positive:
- Complete audit trail by design
- Time-travel debugging capabilities
- Natural fit for regulatory reporting

Negative:
- Increased storage requirements
- Query complexity for current state
- Team learning curve

**Alternatives Considered:**

1. Database triggers + audit table: Rejected due to trigger maintenance burden
2. Change data capture: Rejected due to coupling to database technology
3. Manual audit logging: Rejected due to error-prone implementation

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New feature description

### Changed
- Changes in existing functionality

### Fixed
- Bug fix description

## [1.2.0] - 2024-01-15

### Added
- User profile management (#123)
- Export to CSV functionality (#145)

### Changed
- Updated dependencies to latest versions
- Improved error messages for validation failures

### Fixed
- Fixed race condition in payment processing (#156)
- Corrected timezone handling in reports (#162)

def calculate_shipping_cost(
    weight: float,
    destination: str,
    express: bool = False
) -> Decimal:
    """Calculate shipping cost based on package weight and destination.

    Applies tiered pricing based on weight brackets and adds surcharges
    for international destinations and express delivery.

    Args:
        weight: Package weight in kilograms. Must be positive.
        destination: ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB').
        express: If True, uses express delivery (2-3 days).
                 Default is standard delivery (5-7 days).

    Returns:
        The calculated shipping cost in USD as a Decimal.

    Raises:
        ValueError: If weight is not positive.
        InvalidDestinationError: If country code is not recognized.

    Example:
        >>> calculate_shipping_cost(2.5, 'US')
        Decimal('12.50')
        >>> calculate_shipping_cost(2.5, 'GB', express=True)
        Decimal('45.00')
    """

/// Manages user authentication and session handling.
///
/// This service handles the complete authentication lifecycle including
/// login, token validation, and session management. Tokens are JWTs
/// with a 24-hour expiration.
///
/// # Examples
///
/// ```
/// use auth::AuthService;
///
/// let auth = AuthService::new(config);
/// let token = auth.login("user@example.com", "password").await?;
/// let user = auth.validate_token(&token)?;
/// ```
///
/// # Errors
///
/// Returns `AuthError::InvalidCredentials` if login fails.
/// Returns `AuthError::TokenExpired` if token validation fails.
pub struct AuthService {
    // fields
}

impl AuthService {
    /// Authenticates a user with email and password.
    ///
    /// # Arguments
    ///
    /// * `email` - User's email address
    /// * `password` - User's password (will be hashed before comparison)
    ///
    /// # Returns
    ///
    /// JWT access token valid for 24 hours
    ///
    /// # Errors
    ///
    /// Returns error if credentials are invalid or account is locked
    pub async fn login(&self, email: &str, password: &str) -> Result<String, AuthError> {
        // Implementation
    }
}

## Create User

Creates a new user account.

**Endpoint:** `POST /api/v1/users`

**Authentication:** Required (Admin role)

**Request Body:**
| Field | Type | Required | Description |
|-----------|--------|----------|--------------------------------|
| email | string | Yes | Valid email address |
| name | string | Yes | Full name (2-100 characters) |
| role | string | No | User role. Default: "member" |

**Example Request:**

    POST /api/v1/users
    Authorization: Bearer eyJhbGc...
    Content-Type: application/json

    {
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "admin"
    }

**Success Response (201 Created):**

    {
      "id": "usr_abc123",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "admin",
      "createdAt": "2024-01-15T10:30:00Z"
    }

**Error Responses:**
| Status | Code | Description |
|--------|-------------------|---------------------------------|
| 400 | INVALID_EMAIL | Email format is invalid |
| 400 | NAME_TOO_SHORT | Name must be at least 2 chars |
| 409 | EMAIL_EXISTS | Email already registered |
| 403 | FORBIDDEN | Insufficient permissions |

// BAD: States the obvious
// Increment counter by 1
counter += 1;

// GOOD: Explains why
// Skip the first record as it's always the CSV header
counter += 1;

// BAD: Doesn't add value
// Check if user is valid
if user.is_valid() {

// GOOD: Explains non-obvious business rule
// Users created before 2020 don't have email verification enabled
if user.is_valid() {