Audit logs SDK

The SDK is an npm package that sends audit-log records to the durable SQS ingest queue.

Using the SDK in your project

First, install it:

npm i @payfit/audit-log

Then, instantiate a client:

import { AuditLogger } from '@payfit/audit-log'

const logger = new AuditLogger({
  environment: 'dev', // must be one of: dev, staging, prod
  service: 'the-name-of-the-service',
})

You can finally write an audit log:

logger.log({
  namespace: 'payroll',
  target: 'employee.bonus',
  event: 'create',
  payload: {
    amount: 200,
  },
  account: {
    internalId: 'an internal id',
    individualId: 'an invidiaul id',
    employeeId: 'an employee id',
  },
  scope: {
    employeeId: 'another employee id',
    companyId: 'a company id',
  },
})

Validation and failure handling

Before sending an audit log to SQS, the SDK validates values that would either fail PostgreSQL persistence or be changed silently by JSON.stringify.

Validation rejects:

• U+0000 and unpaired UTF-16 surrogates in persisted strings
• Empty required fields and strings exceeding their PostgreSQL column limit
• Circular references and BigInt values
• undefined, functions, and symbols in payload or scope
• NaN, Infinity, and -Infinity in payload or scope

userIp is forwarded unchanged so non-standard but recoverable values are not discarded.

AuditLogger.log() remains non-throwing. On validation failure, it does not send the record to SQS, increments the validation_failed metric, and emits an audit-log validation failed error containing validation.path and validation.reason. The error also contains the complete audit record so it can be recovered; configure log access and retention accordingly because the record may contain personal data.

Contributing

Building the SDK

The SDK's transport is maintained TypeScript code. It publishes records to SQS and retains the public AuditLogger contract while the consumer persists records directly to Aurora.

To build it, simply run

corepack yarn nx run sdk:build

from the repository root (where the workspace package.json is located).

Testing

Run the SDK test suite from the repository root:

corepack yarn nx run sdk:test

Playing around with the SDK

Could it be for testing some changes you made, or just to discover how to use the SDK, there is a playground at your disposal.

It uses the current code in the repository, not the published one, so you don't have to npm publish or npm link to make it work 🙂

To run it, run from the repository root:

corepack yarn workspace @payfit/audit-log start:playground