# Project Name

Brief description (1-2 sentences).

## Features

- Feature 1
- Feature 2

## Installation

```bash
npm install package-name

import { thing } from 'package-name';
// Minimal working example

## JSDoc/TSDoc Comments

### Functions
```typescript
/**
 * Calculates the total price including tax.
 *
 * @param basePrice - The price before tax
 * @param taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
 * @returns The total price with tax applied
 *
 * @example
 * ```ts
 * const total = calculateTotal(100, 0.08);
 * // Returns: 108
 * ```
 *
 * @throws {RangeError} If taxRate is negative
 */
function calculateTotal(basePrice: number, taxRate: number): number {
  if (taxRate < 0) throw new RangeError('Tax rate cannot be negative');
  return basePrice * (1 + taxRate);
}

/**
 * Manages user authentication and session state.
 *
 * @remarks
 * This class handles OAuth2 authentication flows and maintains
 * session tokens in secure storage.
 *
 * @example
 * ```ts
 * const auth = new AuthManager({ clientId: 'xxx' });
 * await auth.login();
 * const user = auth.getCurrentUser();
 * ```
 */
class AuthManager {
  /**
   * Creates a new AuthManager instance.
   * @param config - Authentication configuration options
   */
  constructor(config: AuthConfig) {}

  /**
   * Initiates the login flow.
   * @returns Promise that resolves when authentication completes
   */
  async login(): Promise<void> {}
}

/**
 * Configuration options for the API client.
 */
interface ApiClientConfig {
  /**
   * Base URL for all API requests.
   * @example "https://api.example.com/v1"
   */
  baseUrl: string;

  /**
   * Request timeout in milliseconds.
   * @default 30000
   */
  timeout?: number;

  /**
   * Custom headers to include in all requests.
   */
  headers?: Record<string, string>;
}

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
  description: API for managing users

paths:
  /users:
    get:
      summary: List all users
      description: Returns a paginated list of users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    $ref: '#/components/schemas/Pagination'

## Create User

Creates a new user account.

### Request

`POST /api/v1/users`

#### Headers

| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |

#### Body

```json
{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user"
}

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "createdAt": "2025-01-02T12:00:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "email": "Invalid email format"
    }
  }
}

## Code Examples

### Good Example
```typescript
// ✅ Shows real use case with context
import { createClient } from 'my-api';

const client = createClient({
  apiKey: process.env.API_KEY,
  region: 'us-east-1',
});

// Fetch user with error handling
try {
  const user = await client.users.get('user_123');
  console.log(`Found user: ${user.name}`);
} catch (error) {
  if (error.code === 'NOT_FOUND') {
    console.log('User does not exist');
  } else {
    throw error; // Re-throw unexpected errors
  }
}

// ❌ Too abstract, no context
const client = new Client(options);
const result = client.doThing(data);

# Changelog

## [1.2.0] - 2025-01-02

### Added
- New `exportToPDF()` method for reports (#123)
- Support for custom themes

### Changed
- Improved performance of data loading by 40%
- Updated minimum Node.js version to 18

### Fixed
- Fixed memory leak in long-running processes (#456)
- Corrected timezone handling for scheduled tasks

### Deprecated
- `legacyExport()` - use `exportToPDF()` instead

### Security
- Updated dependencies to patch CVE-2025-XXXX