# @elliemae/pui-service-sdk

SDK for creating secure, production-ready Node.js microservices.

[Build Job](https://jenkinsbuild.elliemae.cloud/job/UIPlatform/job/service-sdk/job/master/) | [SonarQube Report](https://sonar.ellielabs.com/overview?id=pui-service-sdk-master)

## Features

- **Pre-configured Express app** with security headers (Helmet), CORS, compression, and HTTP parameter pollution protection
- **Structured logging** with Pino, automatic PII redaction, and correlation IDs
- **Redis caching** with in-memory fallback for resilience during outages
- **OAuth2/JWT token management** with JWKS verification and Redis-backed caching
- **AWS Parameter Store** integration for secrets and configuration
- **HTTP client** with configurable retry logic and linear backoff
- **Request validation** middleware via express-validator
- **Serverless support** for AWS Lambda via `@vendia/serverless-express`
- **Graceful shutdown** with SIGINT/SIGTERM handling and cleanup hooks
- **Built-in `/health` endpoint**

## Prerequisites

- Node.js >= 20
- pnpm >= 8

## Installation

```bash
pnpm add @elliemae/pui-service-sdk
```

## Quick Start

```typescript
import { initApp, listen, service, logger } from '@elliemae/pui-service-sdk';

const log = logger({
  appName: 'my-service',
  team: 'my-team',
});

const routes = (app) => {
  app.get('/api/hello', (req, res) => {
    res.json({ message: 'Hello, world!' });
  });
};

const app = initApp();
service.handleRequest({ logger: log, routes: [routes] })(app);
listen(app);
```

## API Overview

### Top-level Exports

| Export                               | Description                                        |
| ------------------------------------ | -------------------------------------------------- |
| `initApp(options?)`                  | Create a pre-configured Express app                |
| `listen(app, options?)`              | Start the HTTP server with graceful shutdown       |
| `serverless(app)`                    | Wrap Express app for AWS Lambda                    |
| `logger(options)`                    | Create a structured Pino logger with PII redaction |
| `validate(validations, statusCode?)` | Express validation middleware                      |
| `customValidators`                   | Built-in validators (`isArray`, `notEmpty`)        |
| `APIError`                           | Error class thrown by `apiRequest`                 |

### Service Namespace

| Export                                      | Description                                 |
| ------------------------------------------- | ------------------------------------------- |
| `service.handleRequest({ logger, routes })` | Wire routes and error handlers onto an app  |
| `service.apiRequest(options)`               | HTTP client with retry logic                |
| `service.RedisService`                      | Redis Cluster cache with in-memory fallback |
| `service.TokenService`                      | OAuth2 token retrieval and JWT verification |
| `service.ParamStoreService`                 | AWS SSM Parameter Store client              |

## Documentation

See the full [Getting Started](./docs/index.md) guide and [User Guide](./docs/guide.md) for detailed usage of each module.

## Development

```bash
pnpm install          # Install dependencies
pnpm run build        # Production build
pnpm run test         # Run tests
pnpm run test:watch   # Run tests in watch mode
pnpm run lint         # Lint
pnpm run lint:fix     # Lint and auto-fix
pnpm run docs:start   # Start documentation site
```

## License

MIT
