Lambda Wrapper

A shared library for Felloh serverless projects that provides core functionality including dependency injection, logging, request handling, database entities, and response models for AWS Lambda functions.

Installation

npm install @felloh-org/lambda-wrapper
# or
yarn add @felloh-org/lambda-wrapper

Quick Start

import { LambdaWrapper, DEFINITIONS, ResponseModel } from '@felloh-org/lambda-wrapper';

const configuration = {
  SERVICE_NAME: 'my-service',
};

export const handler = LambdaWrapper(configuration, async (di, request) => {
  const logger = di.get(DEFINITIONS.LOGGER);
  const warehouse = di.get(DEFINITIONS.WAREHOUSE);

  logger.info('Processing request');

  // Your handler logic here

  return new ResponseModel({ message: 'Success' }, 200).generate();
});

Features

Lambda Wrapper

The core wrapper provides:

• Dependency Injection - Access services via di.get(DEFINITIONS.SERVICE_NAME)
• Automatic Error Handling - Catches and formats errors consistently
• Request Parsing - Parses body, query params, path params, and headers
• Logging & Metrics - Built-in logging with automatic metric collection
• Warm-up Support - Handles serverless-plugin-warmup events automatically

Built-in Services

Access these via di.get(DEFINITIONS.SERVICE_NAME):

| Service | Definition | Description | |---------|------------|-------------| | Logger | DEFINITIONS.LOGGER | Structured logging with metric support | | Request | DEFINITIONS.REQUEST | Parsed request data (body, params, headers) | | Warehouse | DEFINITIONS.WAREHOUSE | TypeORM database connection manager | | Authentication | DEFINITIONS.AUTHENTICATION | JWT authentication and user context | | EventBridge | DEFINITIONS.EVENT_BRIDGE | AWS EventBridge event publishing | | Secrets | DEFINITIONS.SECRETS | AWS Secrets Manager integration | | HTTP | DEFINITIONS.HTTP | HTTP client for external requests | | Webhook | DEFINITIONS.WEBHOOK | Webhook dispatch service | | User | DEFINITIONS.USER | User service utilities | | AuditLogger | DEFINITIONS.AUDIT_LOGGER | Audit trail logging |

Response Model

All Lambda responses are standardised:

import { ResponseModel } from '@felloh-org/lambda-wrapper';

// Success response
return new ResponseModel({ users: [...] }, 200).generate();

// Error response
return new ResponseModel({}, 400)
  .setErrors([{ field: 'email', message: 'Invalid email' }])
  .generate();

Response format:

{
  "statusCode": 200,
  "headers": {
    "Content-Type": "application/json",
    "Access-Control-Allow-Origin": "*"
  },
  "body": {
    "data": { ... },
    "errors": [],
    "meta": {
      "code": 200,
      "reason": "OK",
      "message": "Success",
      "request_id": "uuid"
    }
  }
}

Database Entities (TypeORM)

The library includes TypeORM entities organised by domain:

| Domain | Description | |--------|-------------| | payment | Transactions, refunds, chargebacks, payment links, providers | | user | Users, organisations, roles, features, webhooks | | bank | Accounts, ledgers, settlements, disbursals | | agent-data | Bookings, components, suppliers | | acquirer | BIN data, batches, adjustments | | aisp | Open banking transactions and connections | | nuapay | Nuapay integration entities | | nuvei | Nuvei payment processor entities | | trust-payments | Trust Payments integration | | total-processing | Total Processing integration | | planet | Planet payment processor entities | | saltedge | Saltedge banking integration | | basis-theory | Tokenisation entities | | go-cardless | GoCardless Direct Debit | | marketing | Marketing contacts and ESUs |

EventBridge Events

Publish events to AWS EventBridge:

import { LambdaWrapper, DEFINITIONS, TransactionCustomerReceipt } from '@felloh-org/lambda-wrapper';

export const handler = LambdaWrapper(configuration, async (di, request) => {
  const eventBridge = di.get(DEFINITIONS.EVENT_BRIDGE);

  const event = new TransactionCustomerReceipt();
  event.setCustomerEmail('[email protected]');
  event.setOrgName('Acme Travel');
  event.setAmount(150000);
  event.setCurrencyMajorUnit('GBP');
  event.setId('txn_123');

  await eventBridge.send(event);
});

See Event Documentation for all available events.

Dependency Injection

Create custom services by extending DependencyAwareClass:

import { DependencyAwareClass, DEFINITIONS } from '@felloh-org/lambda-wrapper';

class MyCustomService extends DependencyAwareClass {
  async doSomething() {
    const logger = this.di.get(DEFINITIONS.LOGGER);
    const warehouse = this.di.get(DEFINITIONS.WAREHOUSE);

    // Your service logic
  }
}

// Register in configuration
const configuration = {
  DEPENDENCIES: {
    MY_SERVICE: MyCustomService,
  },
};

Development

Commands

# Build for production (webpack)
yarn build

# Build for TypeORM migrations (babel)
yarn build:orm

# Run linter
yarn lint

# Run tests with coverage
yarn test

# Run database migrations
yarn orm:migration:run

# Generate a new migration
yarn orm:migration:generate <name>

# Revert last migration
yarn orm:revert

# Create database schemas
yarn orm:schema:create

Environment Variables

| Variable | Description | |----------|-------------| | SERVICE_NAME | Service identifier for logging and events | | EVENT_BRIDGE_ARN | AWS EventBridge bus ARN | | DB_HOST | Database host | | DB_PORT | Database port | | DB_USERNAME | Database username | | DB_PASSWORD | Database password | | DB_DATABASE | Database name |

Project Structure

src/
├── config/          # Dependency definitions
├── dependency-injection/  # DI implementation
├── entity/          # TypeORM entities by domain
├── event/           # EventBridge event classes
├── migration/       # Database migrations by schema
├── model/           # Response and data models
├── service/         # Core services
├── util/            # Utility functions
└── wrapper/         # Lambda wrapper implementation

License

MIT