---
title: "Logger"
---

Logger (hereinafter the "Application") is a custom logging utility that provides a wrapper around a custom alert monitoring server, enabling applications to pipe errors and log messages to a centralised alerting system.

## 1. User Documentation

This section is for those interacting with a live instance of the Application.

### Installation

Install the package using your preferred package manager:

```bash
npm install @nhcarrigan/logger
```

```bash
pnpm add @nhcarrigan/logger
```

```bash
yarn add @nhcarrigan/logger
```

### Quick Start

```typescript
import { Logger } from "@nhcarrigan/logger";

// Initialize the logger
const logger = new Logger("my-app", "your-api-token");

// Send log messages
await logger.log("info", "Application started successfully");
await logger.log("warn", "This is a warning message");
await logger.log("debug", "Debug information");

// Send error reports
try {
  // Your code here
} catch (error) {
  await logger.error("functionName", error);
}
```

### API Reference

#### Constructor

```typescript
new Logger(application: string, token: string, url?: string)
```

**Parameters:**
- `application` (string): The name of your application (will appear in logs)
- `token` (string): Your API token for the monitoring service
- `url` (optional string): Custom URL for your own alerting instance (defaults to "https://alerts.nhcarrigan.com")

#### Methods

##### `log(level: Level, message: string): Promise<void>`

Sends a log message to the alerting service.

**Parameters:**
- `level` (Level): The log level - one of "debug", "info", or "warn"
- `message` (string): The message to send

##### `error(context: string, error: Error): Promise<void>`

Sends an error to the alerting service with stack trace information.

**Parameters:**
- `context` (string): A brief description of where the error occurred (e.g., function name)
- `error` (Error): The Node.js error object

### Log Levels

The Application supports three log levels:
- `"debug"`: Debug information for development purposes
- `"info"`: General informational messages
- `"warn"`: Warning messages that don't halt execution

### Custom Alerting Server

By default, the logger sends data to `https://alerts.nhcarrigan.com`. You can configure it to use your own alerting instance by providing a custom URL in the constructor.

## 2. Technical Documentation

This section is for those interested in running their own instance of the Application.

### Architecture

The Application is built as a TypeScript class that wraps HTTP requests to an alerting server. It provides two main endpoints:

1. `/log` - For general log messages
2. `/error` - For error reporting with stack traces

### API Endpoints

#### POST /log

Sends structured log data:

```json
{
  "application": "your-app-name",
  "level": "info",
  "message": "Your log message"
}
```

#### POST /error

Sends structured error data:

```json
{
  "application": "your-app-name",
  "context": "function-name",
  "message": "Error message",
  "stack": "Stack trace information"
}
```

### Authentication

All requests require an `Authorization` header with your API token.

### Development Setup

1. Clone the repository:
   ```bash
   git clone https://git.nhcarrigan.com/NHCarrigan/logger.git
   ```

2. Install dependencies:
   ```bash
   pnpm install
   ```

3. Build the project:
   ```bash
   pnpm run build
   ```

4. Run linting:
   ```bash
   pnpm run lint
   ```

### Project Structure

```
src/
├── index.ts          # Main Logger class
└── types/
    └── level.ts      # Log level type definitions
```

### TypeScript Configuration

The project uses:
- `@nhcarrigan/typescript-config` for TypeScript configuration
- `@nhcarrigan/eslint-config` for ESLint rules
- ES modules (`"type": "module"`)

## 3. Legal Documentation

This section is for expansions to our legal policies specific to the Application.

### License

This software is licensed under Naomi's Public Licence. See the [LICENSE.md](LICENSE.md) file for complete terms.

### Copyright

Copyright held by Naomi Carrigan.

### Privacy

See [PRIVACY.md](PRIVACY.md) for privacy policy information.

### Terms of Service

See [TERMS.md](TERMS.md) for terms of service.

### Security

See [SECURITY.md](SECURITY.md) for security policy and vulnerability reporting procedures.

## 4. Contributing Documentation

This section is for documentation related to contributing to the Application's codebase.

### Getting Started

1. Read our [Code of Conduct](CODE_OF_CONDUCT.md)
2. Review our [Contributing Guidelines](CONTRIBUTING.md)
3. Fork the repository
4. Create a feature branch
5. Make your changes
6. Submit a Pull Request

### Development Guidelines

- Follow the existing code style enforced by ESLint
- Ensure TypeScript compilation passes without errors
- Add appropriate JSDoc comments for new public methods
- Test your changes thoroughly

### Issue Reporting

If you encounter bugs or have feature requests:

1. Check existing issues first
2. Create a new issue with detailed information
3. Include reproduction steps for bugs
4. Tag issues appropriately

### Contact

- Chat Server: [https://chat.nhcarrigan.com](https://chat.nhcarrigan.com)
- Email: contact@nhcarrigan.com
- Repository: [https://git.nhcarrigan.com/nhcarrigan/logger](https://git.nhcarrigan.com/NHCarrigan/logger)
- Issues: Post in the [Bug Reports](https://support.nhcarrigan.com/c/bug-reports/6) or [Feature Requests](https://support.nhcarrigan.com/c/feature-requests/7) categories on our support forum

### Package Information

- **Package Name**: @nhcarrigan/logger
- **Version**: 1.0.0
- **NPM**: [https://www.npmjs.com/package/@nhcarrigan/logger](https://www.npmjs.com/package/@nhcarrigan/logger)
- **Repository**: Git-based repository hosted at git.nhcarrigan.com
