Skip to content
Logger

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

Section titled “1. User Documentation”

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

Installation

Section titled “Installation”

Install the package using your preferred package manager:

Terminal window
npm install @nhcarrigan/logger
Terminal window
pnpm add @nhcarrigan/logger
Terminal window
yarn add @nhcarrigan/logger

Quick Start

Section titled “Quick Start”
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

Section titled “API Reference”

Constructor

Section titled “Constructor”
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.spellware.dev”)

Methods

Section titled “Methods”
log(level: Level, message: string): Promise<void>
Section titled “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>
Section titled “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

Section titled “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

Section titled “Custom Alerting Server”

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

2. Technical Documentation

Section titled “2. Technical Documentation”

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

Architecture

Section titled “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

Section titled “API Endpoints”

POST /log

Section titled “POST /log”

Sends structured log data:

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

POST /error

Section titled “POST /error”

Sends structured error data:

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

Authentication

Section titled “Authentication”

All requests require an Authorization header with your API token.

Development Setup

Section titled “Development Setup”

  1. Clone the repository:

    Terminal window
    git clone https://github.com/spellware/logger.git

  2. Install dependencies:

    Terminal window
    pnpm install

  3. Build the project:

    Terminal window
    pnpm run build

  4. Run linting:

    Terminal window
    pnpm run lint

Project Structure

Section titled “Project Structure”
src/
├── index.ts          # Main Logger class
└── types/
    └── level.ts      # Log level type definitions

TypeScript Configuration

Section titled “TypeScript Configuration”

The project uses:

  • @nhcarrigan/typescript-config for TypeScript configuration
  • @nhcarrigan/eslint-config for ESLint rules
  • ES modules ("type": "module")
Section titled “3. Legal Documentation”

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

License

Section titled “License”

This software is licensed under Naomi’s Public Licence. See the LICENSE.md file for complete terms.

Section titled “Copyright”

Copyright held by Naomi Carrigan.

Privacy

Section titled “Privacy”

See PRIVACY.md for privacy policy information.

Terms of Service

Section titled “Terms of Service”

See TERMS.md for terms of service.

Security

Section titled “Security”

See SECURITY.md for security policy and vulnerability reporting procedures.

4. Contributing Documentation

Section titled “4. Contributing Documentation”

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

Getting Started

Section titled “Getting Started”
  1. Read our Code of Conduct
  2. Review our Contributing Guidelines
  3. Fork the repository
  4. Create a feature branch
  5. Make your changes
  6. Submit a Pull Request

Development Guidelines

Section titled “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

Section titled “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

Section titled “Contact”

Package Information

Section titled “Package Information”