npm package: @quicore/loggable
Description: A comprehensive, class-based logging library for creating standardized activity logs in JavaScript.
Author: quicore
Latest version: 0.2.0

# @quicore/loggable

A comprehensive, class-based logging library for creating standardized and extensible activity logs in JavaScript.

This package provides a set of classes built around a core `Loggable` base class, allowing you to easily construct detailed and consistent log objects that can be serialized to JSON.

### Features

  * **Class-Based Design:** Use familiar object-oriented patterns to build your logs.
  * **Reduced Boilerplate:** A central `Loggable` class handles getters, setters, and JSON serialization, keeping your code clean.
  * **Standardized Structure:** Create logs with a consistent schema, making them easier to parse and analyze.
  * **Extensible:** Easily add new fields or custom classes by extending `Loggable`.

### Installation

```bash
npm install @quicore/loggable
```

### Usage

You can import all classes from the main entry point of the package.

```javascript
import {
  ActivityLog,
  Agent,
  Detail,
  EventSource,
  HttpRequest,
  Loggable,
  Network,
  Outcome,
  Process,
  Resource,
  User,
} from '@quicore/loggable';

// Example Usage:
const log = new ActivityLog('authentication', 'login', 'info');
log.description = 'User login attempt';

const user = new User('user123', 'human');
const network = new Network('192.168.1.100', 'client.example.com');
const agent = new Agent(user, network);

log.addAgent(agent);

const resource = new Resource('application', 'login-service');
log.addResource(resource);

const outcome = new Outcome('SUCCESS', 'Login successful');
log.outcome = outcome;

console.log(JSON.stringify(log.toJSON(), null, 2));

/*
Output:
{
  "type": "authentication",
  "action": "login",
  "severity": "info",
  "occurred": {
    "start": "2023-10-27T10:00:00.000Z", // Actual date/time will vary
    "end": "2023-10-27T10:00:00.000Z"
  },
  "recordedAt": "2023-10-27T10:00:00.000Z",
  "subtype": [],
  "tags": [],
  "source": [],
  "detail": [],
  "agent": [
    {
      "user": {
        "uid": "user123",
        "type": "human",
        "roles": [],
        "groups": []
      },
      "network": {
        "ip": "192.168.1.100",
        "host": "client.example.com"
      }
    }
  ],
  "resource": [
    {
      "type": "application",
      "name": "login-service"
    }
  ],
  "outcome": {
    "code": "SUCCESS",
    "detail": "Login successful"
  }
}
*/
```

### API Reference

#### Core Classes

  * `Loggable`: The base class from which all other classes inherit. Provides core functionality like the `toJSON()` method.
  * `ActivityLog`: The main class for an activity log event. It aggregates all other classes and is the primary object you will work with.

#### Supporting Classes

  * `Outcome`: Describes the result of an activity (e.g., `SUCCESS`, `FAILURE`).
  * `Network`: Captures network-related information like IP addresses and hostnames.
  * `EventSource`: Defines the source of the event (e.g., an application, system, or vendor).
  * `Detail`: A flexible class for adding custom key-value pairs to a log.
  * `HttpRequest`: Stores details about an HTTP request.
  * `User`: Contains user-specific information.
  * `Resource`: Describes the target of the activity, such as a file or database.
  * `Process`: Holds information about a process or service.
  * `Agent`: Represents the actor that initiated the activity, combining `User` and `Network` data.

### License

Distributed under the MIT License. See `LICENSE` for more information.