piper-utils 1.1.62 → 1.1.63

package/README.md

@@ -1,759 +1,846 @@
-# Piper Utils
-
-Production-ready utilities for building AWS Lambda microservices with Cognito authentication and Sequelize ORM. Simplifies common patterns for API Gateway responses, database queries, access control, and AWS service integrations.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Installation](#installation)
-- [Core Concepts](#core-concepts)
-- [Real-World Examples](#real-world-examples)
-  - [Complete Lambda Handler](#complete-lambda-handler)
-  - [Authentication & Access Control](#authentication--access-control)
-  - [Database Query Building](#database-query-building)
-  - [Transaction Management](#transaction-management)
-  - [Error Handling](#error-handling)
-- [Event Manager](#event-manager)
-  - [watchBucket](#watchbucket)
-  - [handleFile](#handlefile)
-  - [handleEvents](#handleevents)
-  - [publishEvents](#publishevents)
-- [API Reference](#api-reference)
-- [Testing](#testing)
-- [Contributing](#contributing)
-
-## Overview
-
-Piper Utils provides battle-tested utilities extracted from production microservices, focusing on:
-
-- **Lambda Integration**: Request/response helpers for API Gateway
-- **Cognito Auth**: User context extraction and access control
-- **Sequelize Helpers**: Query string to ORM translation
-- **AWS Services**: S3 and SNS utilities
-- **Event Management**: S3 bucket watching and file processing
-- **Error Handling**: Consistent error responses
-- **Audit Trail**: Automatic change tracking
-
-## Installation
-
-```bash
-npm install piper-utils
-```
-
-## Core Concepts
-
-### Import Everything You Need
-
-```js
-import { 
-  // Authentication & Access
-  accessRightsUtils,
-  checkModule,
-  checkWriteAccess,
-  getCurrentUser,
-  userDefaultBid,
-  
-  // Database Queries
-  createFilters,
-  createSort,
-  createIncludes,
-  defaultFilters,
-  findAll,
-  
-  // Request/Response
-  parseBody,
-  success,
-  failure,
-  
-  // Event Management
-  watchBucket,
-  handleFile,
-  handleEvents,
-  publishEvents,
-  
-  // AWS Services
-  S3Utils,
-  SNSUtils
-} from 'piper-utils';
-```
-
-## Real-World Examples
-
-### Complete Lambda Handler
-
-A production-ready Lambda function with authentication, validation, and database queries:
-
-```js
-import { 
-  accessRightsUtils, 
-  checkModule, 
-  createFilters, 
-  createSort, 
-  failure, 
-  findAll,
-  success 
-} from 'piper-utils';
-import Customer from './models/customer';
-
-export async function getCustomers(event) {
-  try {
-    // 1. Check module permissions
-    checkModule('customer', event);
-    
-    // 2. Get user's allowed business IDs from Cognito
-    const businessIds = accessRightsUtils(event, { useCognitoBid: true });
-    
-    // 3. Parse query parameters
-    const queryParams = event.queryStringParameters || {};
-    
-    // 4. Build Sequelize filters from query string
-    // Example: ?status=Active&createdAt[gte]=2024-01-01&sort=-lastOrderDate&limit=20
-    const where = createFilters(event, customerFilter);
-    const order = createSort(event, customerSort);
-    
-    // 5. Add access control to query
-    where.businessId = businessIds;
-    
-    // 6. Execute query
-    const customers = await findAll(Customer, {
-      where,
-      order,
-      limit: parseInt(queryParams.limit || '10'),
-      offset: parseInt(queryParams.offset || '0')
-    });
-    
-    // 7. Return standardized response
-    return success(customers);
-    
-  } catch (err) {
-    // Automatic error formatting
-    return failure(err);
-  }
-}
-```
-
-### Authentication & Access Control
-
-Extract user context and enforce permissions:
-
-```js
-import { 
-  getCurrentUser,
-  checkWriteAccess,
-  accessRightsUtils,
-  userDefaultBid 
-} from 'piper-utils';
-
-export async function updateCustomer(event) {
-  try {
-    // Get user from Cognito claims
-    const user = getCurrentUser(event);
-    // user = { id, username, email, groups, jwt }
-    
-    // Verify write permissions (throws if unauthorized)
-    const businessId = checkWriteAccess(event);
-    
-    // Get all business IDs user can access
-    const allowedBusinessIds = accessRightsUtils(event, { 
-      useCognitoBid: true 
-    });
-    
-    // Get user's default business
-    const defaultBid = userDefaultBid(event);
-    
-    // Parse request body
-    const updates = parseBody(event);
-    
-    // Secure query with access control
-    const customer = await Customer.findOne({
-      where: {
-        id: event.pathParameters.id,
-        businessId: allowedBusinessIds // Auto-filtered by permissions
-      }
-    });
-    
-    if (!customer) {
-      throw { code: 'NOT_FOUND', statusCode: 404 };
-    }
-    
-    // Update with audit trail
-    customer.set({ 
-      ...updates,
-      updatedBy: user.id,
-      updatedAt: new Date()
-    });
-    await customer.save();
-    
-    return success(customer);
-    
-  } catch (e) {
-    return failure(e);
-  }
-}
-```
-
-### Database Query Building
-
-Convert API query strings to Sequelize queries automatically:
-
-```js
-import { 
-  createFilters,
-  createSort,
-  defaultFilters 
-} from 'piper-utils';
-import { Op } from 'sequelize';
-
-// 1. Define your model schema
-const orderSchema = {
-  orderNumber: { type: db.STRING },
-  status: { type: db.STRING },
-  total: { type: db.DECIMAL },
-  customerId: { type: db.INTEGER },
-  shippingMethod: { type: db.STRING },
-  createdAt: { type: db.DATE },
-  businessId: { type: db.STRING }
-};
-
-// 2. Create filter configuration with relations
-export const orderFilter = defaultFilters(orderSchema, {
-  customer: customerSchema,  // Enable customer.* filtering
-  items: orderItemSchema     // Enable items.* filtering
-});
-
-// 3. Use in Lambda handler
-export async function searchOrders(event) {
-  // Query: /orders?status=Shipped&total[gte]=100&customer.email=john@example.com&sort=-createdAt
-  
-  const where = createFilters(event, orderFilter);
-  // Produces: {
-  //   status: 'Shipped',
-  //   total: { [Op.gte]: 100 },
-  //   '$customer.email$': 'john@example.com'
-  // }
-  
-  const order = createSort(event, orderFilter);
-  // Produces: [['createdAt', 'DESC']]
-  
-  const orders = await Order.findAll({
-    where,
-    order,
-    include: [
-      { model: Customer, as: 'customer' },
-      { model: OrderItem, as: 'items' }
-    ]
-  });
-  
-  return success(orders);
-}
-```
-
-### Transaction Management
-
-Handle complex operations with automatic rollback:
-
-```js
-import { 
-  parseBody,
-  getCurrentUser,
-  checkWriteAccess,
-  success,
-  failure 
-} from 'piper-utils';
-import db from 'sequelize';
-
-export async function createOrder(event) {
-  const t = await db.getConnection().transaction();
-  
-  try {
-    const user = getCurrentUser(event);
-    const businessId = checkWriteAccess(event);
-    const body = parseBody(event);
-    
-    // Validate input
-    await orderSchema.validateAsync(body);
-    
-    // Create order in transaction
-    const order = await Order.create({
-      ...body,
-      businessId,
-      status: 'Pending',
-      createdBy: user.id
-    }, { transaction: t });
-    
-    // Create order items
-    const items = await Promise.all(
-      body.items.map(item => 
-        OrderItem.create({
-          ...item,
-          orderId: order.id
-        }, { transaction: t })
-      )
-    );
-    
-    // Update inventory
-    for (const item of body.items) {
-      const inventory = await Inventory.findOne({
-        where: { partId: item.partId },
-        transaction: t
-      });
-      
-      if (!inventory || inventory.quantity < item.quantity) {
-        throw { 
-          code: 'INSUFFICIENT_INVENTORY',
-          statusCode: 400,
-          partId: item.partId 
-        };
-      }
-      
-      inventory.quantity -= item.quantity;
-      await inventory.save({ transaction: t });
-    }
-    
-    // Send notification
-    await SNSUtils.publish({
-      topicArn: process.env.ORDER_TOPIC,
-      message: { 
-        type: 'ORDER_CREATED',
-        orderId: order.id,
-        customerId: order.customerId,
-        total: order.total
-      }
-    });
-    
-    await t.commit();
-    return success({ order, items });
-    
-  } catch (e) {
-    await t.rollback();
-    return failure(e);
-  }
-}
-```
-
-### Error Handling
-
-Consistent error responses with custom codes:
-
-```js
-import { failure } from 'piper-utils';
-
-// Define your error catalog
-const errorList = {
-  notFound: {
-    code: 'NOT_FOUND',
-    statusCode: 404,
-    message: 'Resource not found'
-  },
-  customerNotFound: {
-    code: 'CUSTOMER_NOT_FOUND',
-    statusCode: 404,
-    message: 'Customer does not exist'
-  },
-  insufficientInventory: {
-    code: 'INSUFFICIENT_INVENTORY',
-    statusCode: 400,
-    message: 'Not enough inventory to fulfill order'
-  },
-  duplicateEmail: {
-    code: 'DUPLICATE_EMAIL',
-    statusCode: 409,
-    message: 'Email address already exists'
-  }
-};
-
-export async function createCustomer(event) {
-  try {
-    const body = parseBody(event);
-    const businessId = checkWriteAccess(event);
-    
-    // Check for duplicate email
-    const existing = await Customer.findOne({
-      where: { 
-        email: body.email,
-        businessId 
-      }
-    });
-    
-    if (existing) {
-      throw errorList.duplicateEmail;
-    }
-    
-    // Create customer
-    const customer = await Customer.create({
-      ...body,
-      businessId,
-      status: 'Active'
-    });
-    
-    return success(customer);
-    
-  } catch (e) {
-    // failure() automatically formats based on error structure
-    return failure(e);
-    // Returns: {
-    //   statusCode: 409,
-    //   body: JSON.stringify({
-    //     code: 'DUPLICATE_EMAIL',
-    //     message: 'Email address already exists'
-    //   })
-    // }
-  }
-}
-```
-
-## Event Manager
-
-The Event Manager module provides utilities for watching S3 buckets and processing file events, perfect for building data ingestion pipelines.
-
-### watchBucket
-
-Monitor an S3 bucket for new files and trigger processing:
-
-```js
-import { watchBucket } from 'piper-utils';
-
-// Basic usage - watch for new files
-watchBucket({
-  bucket: process.env.AWS_S3_BUCKET,
-  onObjectCreated: async (event) => {
-    console.log('New file detected:', event.s3.object.key);
-    // Process the file
-  }
-});
-
-// Lambda function triggered by S3 events
-export async function s3EventHandler(event) {
-  const { handleEvents } = require('piper-utils');
-  
-  // Process S3 event records
-  for (const record of event.Records) {
-    if (record.eventName.startsWith('ObjectCreated')) {
-      await handleEvents(record);
-    }
-  }
-  
-  return { statusCode: 200 };
-}
-```
-
-### handleFile
-
-Process individual files from S3:
-
-```js
-import { handleFile, S3Utils } from 'piper-utils';
-
-export async function processUploadedFile(bucket, key) {
-  try {
-    // handleFile retrieves and processes the file
-    const result = await handleFile({
-      bucket,
-      key,
-      processor: async (fileContent) => {
-        // Custom processing logic
-        const data = JSON.parse(fileContent);
-        
-        // Transform data
-        const transformed = data.map(item => ({
-          ...item,
-          processedAt: new Date()
-        }));
-        
-        return transformed;
-      }
-    });
-    
-    return result;
-  } catch (e) {
-    console.error('File processing failed:', e);
-    throw e;
-  }
-}
-```
-
-### handleEvents
-
-Orchestrate batch event processing:
-
-```js
-import { handleEvents, success, failure } from 'piper-utils';
-
-// Lambda handler for batch processing
-export async function batchProcessor(event) {
-  try {
-    // Process multiple S3 events
-    const results = await handleEvents(event, {
-      parallel: true,  // Process files in parallel
-      maxConcurrency: 5,
-      onError: (error, record) => {
-        // Custom error handling
-        console.error(`Failed to process ${record.s3.object.key}:`, error);
-      }
-    });
-    
-    return success({
-      processed: results.length,
-      results
-    });
-  } catch (e) {
-    return failure(e);
-  }
-}
-```
-
-### publishEvents
-
-Publish processed events to SNS:
-
-```js
-import { publishEvents } from 'piper-utils';
-
-export async function processAndPublish(events) {
-  try {
-    // Process events
-    const processedEvents = events.map(event => ({
-      id: event.id,
-      type: 'FILE_PROCESSED',
-      timestamp: new Date(),
-      data: event
-    }));
-    
-    // Publish to SNS
-    await publishEvents({
-      topicArn: process.env.EVENT_TOPIC,
-      events: processedEvents,
-      batchSize: 10  // Send in batches of 10
-    });
-    
-    return { published: processedEvents.length };
-  } catch (e) {
-    console.error('Failed to publish events:', e);
-    throw e;
-  }
-}
-```
-
-### Complete File Ingestion Pipeline Example
-
-Here's a complete example of a file ingestion pipeline using all event manager utilities:
-
-```js
-import { 
-  watchBucket,
-  handleFile,
-  handleEvents,
-  publishEvents,
-  success,
-  failure 
-} from 'piper-utils';
-
-// Lambda function for CSV file ingestion
-export async function csvIngestionPipeline(event) {
-  try {
-    // 1. Set up bucket watching (for local development)
-    if (process.env.IS_LOCAL) {
-      watchBucket({
-        bucket: process.env.DATA_BUCKET,
-        prefix: 'uploads/',
-        suffix: '.csv',
-        onObjectCreated: async (s3Event) => {
-          await processCSVFile(s3Event);
-        }
-      });
-    }
-    
-    // 2. Handle S3 event (for Lambda)
-    const results = await handleEvents(event, {
-      processor: processCSVFile
-    });
-    
-    return success({ 
-      processed: results.length,
-      files: results 
-    });
-    
-  } catch (e) {
-    return failure(e);
-  }
-}
-
-async function processCSVFile(s3Event) {
-  const bucket = s3Event.s3.bucket.name;
-  const key = s3Event.s3.object.key;
-  
-  // 3. Process the file
-  const data = await handleFile({
-    bucket,
-    key,
-    processor: async (content) => {
-      // Parse CSV
-      const rows = parseCSV(content);
-      
-      // Validate and transform
-      const validRows = rows.filter(row => validateRow(row));
-      
-      // Save to database
-      await Customer.bulkCreate(validRows);
-      
-      return {
-        total: rows.length,
-        valid: validRows.length,
-        invalid: rows.length - validRows.length
-      };
-    }
-  });
-  
-  // 4. Publish completion event
-  await publishEvents({
-    topicArn: process.env.INGESTION_TOPIC,
-    events: [{
-      type: 'CSV_INGESTED',
-      bucket,
-      key,
-      stats: data,
-      timestamp: new Date()
-    }]
-  });
-  
-  return data;
-}
-```
-
-### S3 Event Configuration
-
-To use these utilities with Lambda, configure your S3 bucket to trigger your Lambda function:
-
-**Serverless Framework:**
-```yaml
-functions:
-  fileProcessor:
-    handler: src/handlers/fileProcessor.handler
-    events:
-      - s3:
-          bucket: ${self:custom.dataBucket}
-          event: s3:ObjectCreated:*
-          rules:
-            - prefix: uploads/
-            - suffix: .csv
-```
-
-**AWS CDK:**
-```typescript
-import * as s3 from '@aws-cdk/aws-s3';
-import * as lambda from '@aws-cdk/aws-lambda';
-import * as s3n from '@aws-cdk/aws-s3-notifications';
-
-const bucket = new s3.Bucket(this, 'DataBucket');
-const processorFunction = new lambda.Function(this, 'Processor', {
-  // ... function config
-});
-
-bucket.addEventNotification(
-  s3.EventType.OBJECT_CREATED,
-  new s3n.LambdaDestination(processorFunction),
-  { prefix: 'uploads/', suffix: '.csv' }
-);
-```
-
-## API Reference
-
-### Authentication Functions
-
-- `getCurrentUser(event)` - Extract user from Cognito claims
-- `checkWriteAccess(event)` - Verify write permissions, returns businessId
-- `checkModule(moduleName, event)` - Check module access permissions
-- `accessRightsUtils(event, options)` - Get user's accessible business IDs
-- `userDefaultBid(event)` - Get user's default business ID
-
-### Database Functions
-
-- `createFilters(event, filterConfig)` - Convert query params to WHERE clause
-- `createSort(event, sortConfig)` - Convert sort param to ORDER BY
-- `createIncludes(event)` - Build include array for relations
-- `defaultFilters(schema, relations)` - Create filter configuration
-- `findAll(Model, options)` - Execute findAll with options
-
-### Request/Response Functions
-
-- `parseBody(event)` - Parse JSON request body
-- `success(data, options)` - Format success response
-- `failure(error, options)` - Format error response
-
-### Event Manager Functions
-
-- `watchBucket(options)` - Monitor S3 bucket for new files
-  - `bucket` - S3 bucket name
-  - `prefix` - Optional key prefix filter
-  - `suffix` - Optional key suffix filter
-  - `onObjectCreated` - Callback for new objects
-  
-- `handleFile(options)` - Process a single file from S3
-  - `bucket` - S3 bucket name
-  - `key` - Object key
-  - `processor` - Async function to process file content
-  
-- `handleEvents(event, options)` - Process batch of S3 events
-  - `event` - S3 event from Lambda
-  - `parallel` - Process files in parallel (default: false)
-  - `maxConcurrency` - Max parallel operations
-  - `processor` - Custom processor function
-  - `onError` - Error handler callback
-  
-- `publishEvents(options)` - Publish events to SNS
-  - `topicArn` - SNS topic ARN
-  - `events` - Array of events to publish
-  - `batchSize` - Events per SNS message
-
-### Query String Parameters
-
-Supported operators in query strings:
-
-- `?field=value` - Exact match
-- `?field[gte]=100` - Greater than or equal
-- `?field[gt]=100` - Greater than
-- `?field[lte]=100` - Less than or equal
-- `?field[lt]=100` - Less than
-- `?field[ne]=value` - Not equal
-- `?field[in]=value1,value2` - In array
-- `?field[like]=%pattern%` - SQL LIKE
-- `?sort=-field` - Sort descending (no prefix for ascending)
-- `?limit=20&offset=40` - Pagination
-
-### AWS Service Utilities
-
-#### S3Utils
-```js
-const s3 = new S3Utils();
-await s3.getObject({ Bucket, Key });
-await s3.putObject({ Bucket, Key, Body });
-```
-
-#### SNSUtils
-```js
-await SNSUtils.publish({
-  topicArn: 'arn:aws:sns:...',
-  message: { type: 'EVENT', data: {} },
-  attributes: { source: 'order-service' }
-});
-```
-
-## Testing
-
-Run tests with Jasmine:
-
-```bash
-npm test
-```
-
-## Contributing
-
-1. Fork the repository
-2. Create your feature branch
-3. Add tests for new functionality
-4. Ensure all tests pass
-5. Submit a pull request
-
-## License
-
-MIT License - Copyright (c) Piper
+# Piper Utils
+
+Utility library for building AWS Lambda microservices with Cognito authentication, Sequelize ORM queries, S3 file processing pipelines, and standardized API Gateway responses.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Exports](#exports)
+- [Request / Response](#request--response)
+  - [success](#successbody-options)
+  - [successHtml](#successhtmlhtml-options)
+  - [failure](#failurebody-options)
+  - [parseBody](#parsebodyevent)
+  - [parseEvent](#parseeventevent-callback)
+  - [getCurrentUser](#getcurrentuserevent)
+  - [getCurrentUserNameFromCognitoEvent](#getcurrentusernameFromcognitoeventevent)
+- [Authentication & Access Control](#authentication--access-control)
+  - [accessRightsUtils](#accessrightsutiilsevent-options)
+  - [checkWriteAccess](#checkwriteaccessevent-options)
+  - [checkModule](#checkmodulemodulename-event)
+  - [checkIsSuper](#checkissuperevent)
+  - [isSuperUser / isSystemUser](#issuperuserevent--issystemuserevent)
+  - [isPartnerUser / getBelongsToPartnerId / getEffectivePartnerId](#ispartneruserevent)
+  - [enrichEventWithPartnerAccess](#enricheventwithpartneraccessevent-partnerbusinessids-role)
+  - [userDefaultBid](#userdefaultbidevent)
+  - [getBusinessesInfo](#getbusinessesinfoevent-usecognitobid)
+  - [getAccessRightsInfo / getDefaultBusinessIDInfo / getModuleInfo](#low-level-claim-helpers)
+  - [getCompanySettings](#getcompanysettingsevent)
+- [JWT Claims Reference](#jwt-claims-reference)
+- [Database Query Helpers](#database-query-helpers)
+  - [defaultFilters](#defaultfiltersschema-subschemas)
+  - [createFilters](#createfiltersevent-objectfilters)
+  - [createSort](#createsortevent-defaultfilter)
+  - [createIncludes](#createincludesevent-objectfilters)
+  - [findAll](#findallmodel-options)
+- [Query String DSL](#query-string-dsl)
+- [Event Manager (S3 Pipeline)](#event-manager-s3-pipeline)
+  - [watchBucket](#watchbucketparams)
+  - [handleFile](#handlefilepath-s3bucket-transformer-options)
+  - [handleEvents](#handleeventsevent-transformer-errorhandlerperfile-shouldskipfailedfolders-userimporttypes)
+  - [publishEvents](#publisheventsconfigtable-tablekey-bucket-snstopic-userimporttypes)
+  - [Retry / Error Folder Strategy](#retry--error-folder-strategy)
+- [Database Migrations](#database-migrations)
+- [Built-in Error Codes](#built-in-error-codes)
+- [Examples](#examples)
+- [Peer Dependencies](#peer-dependencies)
+- [Testing](#testing)
+
+## Installation
+
+```bash
+npm install piper-utils
+```
+
+## Exports
+
+Every public function is re-exported from the package root:
+
+```js
+import {
+  // Request / Response
+  success, successHtml, failure, parseBody, parseEvent,
+  getCurrentUser, getCurrentUserNameFromCognitoEvent,
+
+  // Authentication & Access Control
+  accessRightsUtils, checkWriteAccess, checkModule, checkIsSuper,
+  isSystemUser, isSuperUser,
+  isPartnerUser, getBelongsToPartnerId, getEffectivePartnerId,
+  enrichEventWithPartnerAccess,
+  userDefaultBid, getBusinessesInfo,
+  getAccessRightsInfo, getDefaultBusinessIDInfo, getModuleInfo,
+  getCompanySettings,
+
+  // Database Query Helpers (Sequelize)
+  defaultFilters, createFilters, createSort, createIncludes, findAll,
+
+  // Event Manager (S3 Pipeline)
+  watchBucket, handleFile, publishEvents,
+
+  // Database Migrations
+  runMigrations
+} from 'piper-utils';
+```
+
+> **Note:** S3Utils, SNSUtils, and dynamoUtil are internal modules used by the event manager. They are not exported from the package root.
+
+---
+
+## Request / Response
+
+Functions for formatting API Gateway Lambda proxy responses with CORS and security headers.
+
+All JSON responses include these security headers:
+- `Strict-Transport-Security` (HSTS)
+- `X-Content-Type-Options: nosniff`
+- `X-Frame-Options: DENY`
+- `Content-Security-Policy: default-src 'none'; frame-ancestors 'none'`
+- `Referrer-Policy: strict-origin-when-cross-origin`
+- `Permissions-Policy` (camera, microphone, geolocation disabled)
+- `Cache-Control: no-store`
+
+### `success(body, options?)`
+
+Format a 200 JSON response.
+
+```js
+return success({ id: 1, name: 'Widget' });
+// => { statusCode: 200, headers: {...}, body: '{"id":1,"name":"Widget"}' }
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `body` | any | Response data (will be JSON.stringify'd) |
+| `options.dbClose` | function | Optional callback invoked before returning (e.g. close DB connection) |
+
+### `successHtml(html, options?)`
+
+Format a 200 HTML response with a relaxed CSP that allows payment provider scripts (TokenEx, NMI, Apple Pay, Sentry).
+
+```js
+return successHtml('<html>...</html>');
+// => { statusCode: 200, headers: { 'Content-Type': 'text/html', ... }, body: '<html>...</html>' }
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `html` | string | Raw HTML content |
+| `options.dbClose` | function | Optional callback invoked before returning |
+
+### `failure(body?, options?)`
+
+Format an error response. Automatically detects and normalizes Joi, Sequelize, and Dynamoose errors.
+
+```js
+// Throw a known error
+throw { statusCode: 404, errorCode: '4004', message: 'ITEM NOT FOUND' };
+
+// failure() catches and formats it
+return failure(err);
+// => { statusCode: 404, headers: {...}, body: '{"statusCode":404,"errorCode":"4004","message":"ITEM NOT FOUND"}' }
+```
+
+**Auto-detection logic:**
+
+| Error type | Detection | Resulting statusCode / errorCode |
+|------------|-----------|----------------------------------|
+| Joi validation | `body.details` exists | 400 / `4000` |
+| Sequelize ForeignKeyConstraint | `body.name === 'SequelizeForeignKeyConstraintError'` | 409 / `4090` |
+| Sequelize UniqueConstraint | `body.name === 'SequelizeUniqueConstraintError'` | 409 / `4091` |
+| Sequelize ValidationError | `body.name === 'SequelizeValidationError'` | 400 / `4001` |
+| Unknown | fallback | 500 / `5XX` |
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `body` | object/Error | Error object. If it has `statusCode` and `errorCode`, used as-is. |
+| `options.dbClose` | function | Optional callback invoked before returning |
+
+### `parseBody(event)`
+
+Parse the JSON body from an API Gateway Lambda proxy event. Throws `errorList.invalidJson` (400) on malformed JSON.
+
+```js
+const body = parseBody(event);
+// body is the parsed JSON object, or {} if event.body is falsy
+```
+
+Returns the `event.body` as-is if it's already an object (e.g. from serverless-offline).
+
+### `parseEvent(event, callback?)`
+
+Like `parseBody` but for parsing an entire event string. Optionally calls `callback(error)` on failure instead of throwing.
+
+```js
+const parsed = parseEvent(eventString);
+```
+
+### `getCurrentUser(event)`
+
+Extract user info from Cognito JWT authorizer claims.
+
+```js
+const user = getCurrentUser(event);
+// => { username: 'john@example.com', id: 42 }
+```
+
+| Return field | Source claim | Default |
+|-------------|-------------|---------|
+| `id` | `custom:UID` (JSON-parsed) | `0` |
+| `username` | `email` | `'localtestuser@gexample.com'` |
+
+### `getCurrentUserNameFromCognitoEvent(event)`
+
+Extract email from a **Cognito User Pool trigger event** (different structure than API Gateway authorizer events).
+
+```js
+// Inside a Cognito Pre-Sign-Up or Post-Confirmation trigger
+const email = getCurrentUserNameFromCognitoEvent(event);
+// Reads from event.request.userAttributes['cognito:email_alias'] or ['email']
+```
+
+---
+
+## Authentication & Access Control
+
+All auth functions read JWT claims from `event.requestContext.authorizer.claims` (or `event.requestContext.authorizer` for custom authorizers). See [JWT Claims Reference](#jwt-claims-reference) for the full claim structure.
+
+**Local bypass:** When `BUILD_ENV=local`, most auth checks are relaxed to ease development.
+
+### `accessRightsUtils(event, options?)`
+
+Get the list of business IDs the current user is authorized to access. Compares requested IDs (from query string or body) against allowed IDs (from JWT claims).
+
+```js
+const businessIds = accessRightsUtils(event, { useCognitoBid: true });
+// => ['1', '5', '12']
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `event` | object | Lambda event |
+| `options.useCognitoBid` | boolean | If true, prefer Cognito businessId; skip local fallback of BID '1' |
+
+**Returns:** `string[]` - business IDs user can access.
+
+**Behavior by user type:**
+- **Super user:** Gets all requested IDs; if none requested, gets all allowed IDs
+- **System user:** Gets all requested IDs (no filtering)
+- **Regular user:** Gets the intersection of requested and allowed IDs
+
+### `checkWriteAccess(event, options?)`
+
+Verify the user has write (`W`) or admin (`A`) role for the businessId in the request body. Throws `errorList.unauthorized` (401) if denied.
+
+```js
+const businessId = checkWriteAccess(event);
+// Returns the authorized businessId string
+```
+
+**Bypassed for:** super users, system users, `BUILD_ENV=local`.
+
+### `checkModule(moduleName, event)`
+
+Verify the user has access to a named module. Throws `errorList.unauthorized` (401) if denied.
+
+```js
+checkModule('customer', event);   // throws if no access
+checkModule('inventory', event);  // throws if no access
+```
+
+Reads module permissions from `custom:MOD` (falls back to `custom:AR`). **Bypassed for:** super users, system users, `BUILD_ENV=local`.
+
+### `checkIsSuper(event)`
+
+Throws `errorList.unauthorized` (401) if the user is not a super or system user. **Bypassed for** `BUILD_ENV=local`.
+
+```js
+checkIsSuper(event); // throws if not super/system
+```
+
+### `isSuperUser(event)` / `isSystemUser(event)`
+
+Boolean checks. No throwing, no bypass.
+
+```js
+if (isSuperUser(event)) { /* full access */ }
+if (isSystemUser(event)) { /* machine-to-machine */ }
+```
+
+### `isPartnerUser(event)`
+
+Returns the partner ID from `custom:PID`, or `false`.
+
+### `getBelongsToPartnerId(event)`
+
+Returns the partner ID from `custom:BPID` (user's business belongs to a partner), or `false`.
+
+### `getEffectivePartnerId(event)`
+
+Returns `isPartnerUser(event) || getBelongsToPartnerId(event)` - the partner ID from either claim, or `false`.
+
+### `enrichEventWithPartnerAccess(event, partnerBusinessIds, role?)`
+
+Mutate the event's `custom:AR` claim in-memory to add partner business IDs. Call this **before** `accessRightsUtils()` or `getBusinessesInfo()` so partner admins get access to their partner's merchants.
+
+```js
+// After looking up partner's business IDs from your DB:
+enrichEventWithPartnerAccess(event, ['101', '102', '103'], 'R');
+// Now accessRightsUtils(event) will include 101, 102, 103
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `event` | object | | Lambda event (mutated in-place) |
+| `partnerBusinessIds` | string[] | | Business IDs to add |
+| `role` | string | `'R'` | Access role: `'R'` (read), `'W'` (write), `'A'` (admin) |
+
+### `userDefaultBid(event)`
+
+Get the user's default business ID from `custom:DBI`.
+
+```js
+const defaultBid = userDefaultBid(event);
+// => '5' (or '1' as fallback)
+```
+
+### `getBusinessesInfo(event, useCognitoBid?)`
+
+Get the raw business ID to role mapping from `custom:AR`.
+
+```js
+const businesses = getBusinessesInfo(event);
+// => { '1': 'A', '5': 'W', '12': 'R' }
+```
+
+When `BUILD_ENV=local`, automatically injects `{ '1': 'A' }` and any businessId from the request body.
+
+### Low-level Claim Helpers
+
+These extract raw claim values without business logic:
+
+- **`getAccessRightsInfo(event)`** - Returns `custom:AR.businessIds` as an object (e.g. `{ '1': 'A', '5': 'R' }`)
+- **`getDefaultBusinessIDInfo(event)`** - Returns `custom:DBI.defaultBid` as a string (default `'1'`)
+- **`getModuleInfo(event)`** - Returns `custom:MOD.module` (or `custom:AR.module`) as an object
+
+### `getCompanySettings(event)`
+
+Get company-level cached settings from `custom:SET`.
+
+```js
+const settings = getCompanySettings(event);
+// => { auditEnabled: true, ... }
+```
+
+Returns `{}` on parse error.
+
+---
+
+## JWT Claims Reference
+
+The library expects these custom Cognito attributes on `event.requestContext.authorizer.claims` (or `event.requestContext.authorizer` for custom authorizers):
+
+| Claim | Type | Example | Used by |
+|-------|------|---------|---------|
+| `custom:UID` | JSON number | `"42"` | `getCurrentUser` |
+| `email` | string | `"john@example.com"` | `getCurrentUser` |
+| `custom:SYSTEM` | JSON boolean | `"true"` | `isSystemUser` |
+| `custom:SUPER` | JSON boolean | `"true"` | `isSuperUser` |
+| `custom:AR` | JSON object | `{"businessIds":{"1":"A","5":"R"}}` | `accessRightsUtils`, `checkWriteAccess`, `getBusinessesInfo` |
+| `custom:DBI` | JSON object | `{"defaultBid":"5"}` | `userDefaultBid` |
+| `custom:MOD` | JSON object | `{"module":{"customer":true}}` | `checkModule` |
+| `custom:PID` | string | `"PARTNER_123"` | `isPartnerUser` |
+| `custom:BPID` | string | `"PARTNER_123"` | `getBelongsToPartnerId` |
+| `custom:SET` | JSON object | `{"auditEnabled":true}` | `getCompanySettings` |
+
+**Role values** in `custom:AR.businessIds`: `A` (admin), `W` (write), `R` (read).
+
+---
+
+## Database Query Helpers
+
+Utilities for translating API query string parameters into Sequelize queries. These handle filtering, sorting, pagination, and relation includes automatically.
+
+### `defaultFilters(schema, subSchemas?)`
+
+Create a filter configuration object from a Sequelize model schema. This maps each column's data type to the appropriate Sequelize operator.
+
+```js
+import DB from 'sequelize';
+
+const orderSchema = {
+  orderNumber: { type: new DB.STRING() },
+  status: { type: new DB.STRING() },
+  total: { type: new DB.DECIMAL() },
+  active: { type: new DB.BOOLEAN() },
+  metadata: { type: DB.JSONB },
+  createdAt: { type: new DB.DATE() }
+};
+
+const orderFilter = defaultFilters(orderSchema, {
+  customer: customerSchema       // enable customer.* filtering
+});
+```
+
+**Type-to-operator mapping:**
+
+| Sequelize type | Operator | Behavior |
+|---------------|----------|----------|
+| STRING, CHAR, TEXT | `Op.iLike` | Case-insensitive `LOWER(col) LIKE '%value%'` |
+| INTEGER, DECIMAL, BIGINT | `Op.or` | Matches `+value` or `-value` |
+| BOOLEAN | `Op.eq` | Exact match with string-to-boolean coercion |
+| JSONB | (special) | Case-insensitive search via `jsonb_extract_path_text` |
+| DATE | `Op.between` | Range filter |
+| DATEONLY | `Op.eq` | Exact match |
+
+**Auto-added fields:** `id`, `createdAt`, `updatedAt` are always included.
+
+### `createFilters(event, objectFilters)`
+
+Convert query string parameters into a Sequelize WHERE clause. Automatically applies:
+- **Business ID scoping** via `accessRightsUtils(event)`
+- **Active record filtering** (defaults `active: true` if the schema has an `active` column)
+- **Date range filtering** when both `startDate` and `endDate` are provided
+- **Full-text search** when `searchString` is provided
+
+```js
+// URL: /orders?status=Shipped&searchString=john&startDate=2024-01-01&endDate=2024-12-31&sort=-createdAt
+const where = createFilters(event, orderFilter);
+```
+
+See [Query String DSL](#query-string-dsl) for all supported operators.
+
+### `createSort(event, defaultFilter)`
+
+Convert the `sort` query parameter into a Sequelize ORDER BY array.
+
+```js
+// URL: /orders?sort=-createdAt,status
+const order = createSort(event, orderFilter);
+// => [['createdAt', 'DESC'], ['status', 'ASC']]
+```
+
+- Prefix with `-` for DESC, no prefix for ASC
+- Comma-separated for multiple fields
+- **Default:** `-updatedAt` (DESC)
+- Only allows sorting on fields defined in `defaultFilter` (prevents injection)
+
+### `createIncludes(event, objectFilters)`
+
+Build a Sequelize includes array by detecting which relations are referenced in filter or sort parameters (via dot-notation).
+
+```js
+// URL: /orders?customer.email=john@test.com&sort=-customer.name
+const includes = createIncludes(event, orderFilter);
+// => ['customer']
+```
+
+### `findAll(model, options)`
+
+Paginated wrapper around `Model.findAll()`. Fetches `limit + 1` records to detect `hasMore` without a COUNT query.
+
+```js
+const result = await findAll(Order, {
+  where,
+  order,
+  limit: 20,
+  offset: 0,
+  includes: [{ model: Customer, as: 'customer' }]
+});
+// => { offset: 0, limit: 20, rows: [...], hasMore: true }
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | Sequelize.Model | | Sequelize model class |
+| `options.where` | object | | WHERE clause (from `createFilters`) |
+| `options.order` | array | | ORDER BY (from `createSort`) |
+| `options.includes` | array | `{ all: true, nested: true }` | Relations to include |
+| `options.limit` | number | `0` (no limit) | Page size |
+| `options.offset` | number | `0` | Page offset |
+
+**Returns:** `{ offset, limit, rows, hasMore }`
+
+---
+
+## Query String DSL
+
+Supported query string parameters for `createFilters` and `createSort`:
+
+| Query | Behavior |
+|-------|----------|
+| `?field=value` | Match by type: iLike for strings, eq for booleans, or for numbers |
+| `?searchString=john` | OR search across all filterable string/numeric fields |
+| `?startDate=2024-01-01&endDate=2024-12-31` | BETWEEN on `createdAt` |
+| `?sort=-field` | Sort DESC (prefix `-`) |
+| `?sort=field1,-field2` | Multi-field sort, comma-separated |
+| `?token.cardHolderName=gregory` | JSONB dot-notation search (case-insensitive) |
+| `?token={"cardType":"visa"}` | JSONB object search (all key-value pairs, case-insensitive) |
+| `?customer.email=john` | Relation field filter (auto-includes the relation) |
+
+---
+
+## Event Manager (S3 Pipeline)
+
+A set of utilities for building S3 file processing pipelines. The typical flow is:
+
+1. **Cron job** triggers `watchBucket` -> calls `publishEvents` to scan S3 and publish file batches to SNS
+2. **SNS trigger** invokes Lambda -> `watchBucket` routes to `handleEvents` which processes files in parallel
+3. **Direct S3 trigger** invokes Lambda -> `watchBucket` routes to `handleDirectS3WriteEvent`
+
+### `watchBucket(params)`
+
+Entry point for the S3 pipeline. Routes incoming events to the appropriate handler based on event source.
+
+```js
+import { watchBucket } from 'piper-utils';
+
+export async function handler(event) {
+  return watchBucket({
+    event,
+    dynamoConfigTable: 'Config-Dev',
+    dynamoConfigKey: 'importConfig',
+    s3Bucket: 'my-data-bucket',
+    snsTopic: 'my-import-topic',
+    transformer: async (parsedJson) => {
+      // Process each file's parsed JSON content
+      await saveToDatabase(parsedJson);
+    },
+    errorHandlerPerFile: (err, filePath) => {
+      console.error(`Failed: ${filePath}`, err);
+      return false; // return true to suppress error, false to fail
+    },
+    shouldSkipFailedFolders: false,
+    userImportTypes: { orders: 'orders', customers: 'customers' }
+  });
+}
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `event` | object | Yes | Lambda event (SNS, S3, or CloudWatch cron) |
+| `dynamoConfigTable` | string | Yes | DynamoDB table name for pipeline config |
+| `dynamoConfigKey` | string | Yes | Key in DynamoDB table (holds `snsChunkSize` and `snsMaxMessages`) |
+| `s3Bucket` | string | Yes | S3 bucket name to watch |
+| `snsTopic` | string | Yes | SNS topic name for publishing file batches |
+| `transformer` | function | Yes | `async (parsedJson) => result` - processes each file's content |
+| `errorHandlerPerFile` | function | No | `(error, filePath) => boolean` - return `true` to suppress, `false` to fail batch |
+| `shouldSkipFailedFolders` | boolean | No | If `true`, skip retry folders and move directly to `error/` |
+| `userImportTypes` | object | No | Map of import type subdirectories |
+
+**Routing logic:**
+- `EventSource === 'aws:sns'` -> `handleEvents()`
+- `EventSource === 'aws:s3'` -> `handleDirectS3WriteEvent()` (skips files in `failed-once/`, `failed-twice/`, `error/`)
+- `EventSource === 'aws:s3'` with key prefix `DIRECT` -> `handleDirectS3WriteEvent()`
+- Otherwise (cron job, no Records) -> `publishEvents()`
+
+### `handleFile(path, s3Bucket, transformer, options?)`
+
+Process a single file from S3. Downloads the file, parses it as JSON, passes it to the transformer, then deletes the original. On error, moves the file through the retry folder strategy.
+
+```js
+import { handleFile } from 'piper-utils';
+
+const result = await handleFile(
+  'orders/order-123.json',
+  'my-data-bucket',
+  async (parsedJson) => {
+    // parsedJson is the JSON.parse'd file content
+    await Order.create(parsedJson);
+    return { processed: true };
+  },
+  { shouldSkipFailedFolders: false }
+);
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `path` | string | S3 object key |
+| `s3Bucket` | string | S3 bucket name |
+| `transformer` | function | `async (parsedJson) => result` |
+| `options.shouldSkipFailedFolders` | boolean | Skip retry folders, move straight to `error/` |
+| `options.userImportTypes` | object | Import type subdirectories |
+
+**Returns:** The transformer's return value, or `undefined` if the file was empty/missing.
+
+**Behavior:**
+- Returns silently if file not found (`NoSuchKey`)
+- Returns silently (and deletes file) if body is empty, `{}`, or `[]`
+- On success: deletes the original file
+- On error: moves file through retry folders, then re-throws
+
+### `handleEvents(event, transformer, errorHandlerPerFile?, shouldSkipFailedFolders?, userImportTypes?)`
+
+Process a batch of files from SNS-relayed S3 events. Processes files in parallel using `Bluebird.Promise.map`.
+
+```js
+// event.Records[].Sns.Message = JSON.stringify({ bucket: '...', files: ['file1.json', 'file2.json'] })
+await handleEvents(event, transformer, errorHandlerPerFile, false, userImportTypes);
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `event` | object | SNS event with `Records[].Sns.Message` containing `{ bucket, files }` |
+| `transformer` | function | `async (parsedJson) => result` |
+| `errorHandlerPerFile` | function | `(error, filePath) => boolean` - return `true` to suppress |
+| `shouldSkipFailedFolders` | boolean | Default `false` |
+| `userImportTypes` | object | Import subdirectories |
+
+Throws `'ERROR: HANDLE-FILE'` if any file fails and `errorHandlerPerFile` returns `false` (or is not provided).
+
+### `publishEvents(configTable, tableKey, bucket, snsTopic, userImportTypes?)`
+
+Scan an S3 bucket and publish file batches to SNS. Typically called by a cron job via `watchBucket`.
+
+```js
+await publishEvents('Config-Dev', 'importConfig', 'my-data-bucket', 'my-import-topic');
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `configTable` | string | DynamoDB table with pipeline config |
+| `tableKey` | string | Config key (item must have `snsChunkSize` and `snsMaxMessages`) |
+| `bucket` | string | S3 bucket to scan |
+| `snsTopic` | string | SNS topic name |
+| `userImportTypes` | object | Import subdirectories (optional) |
+
+**Config lookup:** Reads `Item.snsChunkSize` (default: 2) and `Item.snsMaxMessages` (default: 10) from DynamoDB.
+
+**File filtering:** Skips files in `error/`, `failed-once/`, `failed-twice/`. Supports `delayUntil/` folder (files processed only after the time encoded in the path, format `YYYYMMDDHHmm`).
+
+**Publishing:** Lists all eligible files, chunks them by `snsChunkSize`, publishes up to `snsMaxMessages` SNS messages. Each message body: `{ bucket, files: [...keys] }`.
+
+### Retry / Error Folder Strategy
+
+When `handleFile` encounters an error processing a file, it moves the file through progressive retry folders before giving up:
+
+```
+file.json  --(error)-->  failed-once/file.json
+                           --(error)-->  failed-twice/file.json
+                                           --(error)-->  error/file.json (terminal)
+```
+
+If `shouldSkipFailedFolders: true`, files go directly to `error/` on first failure.
+
+With `userImportTypes`, the same pattern applies within each import type's subfolder:
+```
+orders/file.json  -->  orders/failed-once/file.json  -->  orders/failed-twice/file.json  -->  orders/error/file.json
+```
+
+Files in `error/` are never reprocessed. A nesting guard prevents double-nesting (e.g. `failed-once/failed-once/file.json`).
+
+---
+
+## Database Migrations
+
+### `runMigrations(databaseName, sequelizeInstance, initializeModels, pathToMigrationFolder?)`
+
+Execute pending database migrations using [Umzug](https://github.com/sequelize/umzug). On failure, rolls back pending migrations before throwing.
+
+```js
+import { runMigrations } from 'piper-utils';
+
+await runMigrations(
+  'my-database',
+  sequelizeInstance,
+  async () => { await sequelizeInstance.sync(); },
+  `${__dirname}/migrations/*.js`   // optional, defaults to ${PWD}/migrations/*.js
+);
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `databaseName` | string | | Database name (for logging) |
+| `sequelizeInstance` | Sequelize | | Initialized Sequelize instance |
+| `initializeModels` | function | | Async function to define/sync models (called after migrations) |
+| `pathToMigrationFolder` | string | `${PWD}/migrations/*.js` | Glob pattern for migration files |
+
+---
+
+## Built-in Error Codes
+
+The library includes a pre-defined `errorList` used internally by auth checks and `parseBody`. These are the error objects that get thrown/returned:
+
+| Key | errorCode | statusCode | Message |
+|-----|-----------|------------|---------|
+| `unauthorized` | 4111 | 401 | UNAUTHORIZED |
+| `notFound` | 4004 | 404 | ITEM NOT FOUND |
+| `invalidJson` | 4005 | 400 | INVALID JSON |
+| `invalidRequest` | 4016 | 400 | INVALID REQUEST DATA |
+| `invalidID` | 4014 | 400 | ID is invalid |
+| `invalidFilter` | 4026 | 400 | INVALID FILTER |
+| `invalidStartDate` | 4020 | 400 | INVALID START DATE |
+| `invalidEndDate` | 4021 | 400 | INVALID END DATE |
+| `invalidDateFormat` | 4019 | 400 | INVALID DATE FORMAT |
+| `invalidAPIKey` | 4017 | 400 | INVALID REQUEST - API MAY KEY INVALID |
+| `invalidUserNameUpdate` | 4027 | 400 | UNABLE TO UPDATE USERNAME |
+| `imageSizeLimit` | 4028 | 400 | IMAGE SIZE LIMIT 100KB EXCEEDED |
+| `emailRequired` | 4004 | 404 | NO EMAIL PROVIDED, CHECK CUSTOMER EMAIL |
+| `mobilePhoneRequired` | 4004 | 404 | NO MOBILE PHONE PROVIDED, CHECK CUSTOMER CONTACTS |
+| `invalidCadenceType` | 5001 | 500 | INVALID CADENCE TYPE |
+
+Consuming services typically define their own `errorList` that extends or mirrors this pattern:
+
+```js
+const errorList = {
+  paymentFailed: { statusCode: 400, errorCode: '4030', message: 'PAYMENT FAILED' }
+};
+
+// Throw it — failure() will format it correctly
+throw errorList.paymentFailed;
+```
+
+---
+
+## Examples
+
+### Complete Lambda Handler (Read)
+
+```js
+import {
+  accessRightsUtils, checkModule,
+  createFilters, createSort, findAll,
+  success, failure
+} from 'piper-utils';
+
+export async function getOrders(event) {
+  try {
+    checkModule('orders', event);
+
+    const where = createFilters(event, orderFilter);
+    const order = createSort(event, orderFilter);
+    const query = event.queryStringParameters || {};
+
+    const result = await findAll(Order, {
+      where,
+      order,
+      limit: parseInt(query.limit || '20'),
+      offset: parseInt(query.offset || '0')
+    });
+
+    return success(result);
+  } catch (err) {
+    return failure(err);
+  }
+}
+```
+
+> Note: `createFilters` automatically scopes the query to the user's authorized business IDs via `accessRightsUtils(event)`. You do not need to add `where.businessId` manually.
+
+### Complete Lambda Handler (Write)
+
+```js
+import {
+  parseBody, getCurrentUser, checkWriteAccess,
+  success, failure
+} from 'piper-utils';
+
+export async function updateOrder(event) {
+  try {
+    const user = getCurrentUser(event);
+    // => { username: 'john@example.com', id: 42 }
+
+    const businessId = checkWriteAccess(event);
+    // Throws 401 if user lacks write/admin role for the businessId in body
+
+    const body = parseBody(event);
+
+    const order = await Order.findOne({
+      where: { id: event.pathParameters.id, businessId }
+    });
+
+    if (!order) throw { statusCode: 404, errorCode: '4004', message: 'Order not found' };
+
+    order.set({ ...body, updatedBy: user.id });
+    await order.save();
+
+    return success(order);
+  } catch (e) {
+    return failure(e);
+  }
+}
+```
+
+### S3 File Processing Pipeline
+
+```js
+import { watchBucket, success, failure } from 'piper-utils';
+
+export async function importHandler(event) {
+  try {
+    return await watchBucket({
+      event,
+      dynamoConfigTable: 'Config-Dev',
+      dynamoConfigKey: 'orderImportConfig',
+      s3Bucket: 'order-imports-dev',
+      snsTopic: 'order-import-topic-dev',
+      transformer: async (parsedJson) => {
+        // Each file contains a JSON order object
+        await Order.create(parsedJson);
+      },
+      errorHandlerPerFile: (err, filePath) => {
+        console.error(`Import failed for ${filePath}:`, err);
+        return false; // don't suppress — let retry folders handle it
+      }
+    });
+  } catch (e) {
+    return failure(e);
+  }
+}
+```
+
+### Partner Access Enrichment
+
+```js
+import {
+  getEffectivePartnerId, enrichEventWithPartnerAccess,
+  accessRightsUtils, success, failure
+} from 'piper-utils';
+
+export async function getPartnerOrders(event) {
+  try {
+    const partnerId = getEffectivePartnerId(event);
+
+    if (partnerId) {
+      // Look up which businesses belong to this partner
+      const partnerBusinessIds = await getPartnerBusinessIds(partnerId);
+      // Inject them into the event so accessRightsUtils includes them
+      enrichEventWithPartnerAccess(event, partnerBusinessIds, 'R');
+    }
+
+    const businessIds = accessRightsUtils(event);
+    // Now includes both user's own businesses AND partner businesses
+
+    // ... query with businessIds
+    return success(results);
+  } catch (e) {
+    return failure(e);
+  }
+}
+```
+
+---
+
+## Peer Dependencies
+
+These must be installed in the consuming project:
+
+| Package | Version |
+|---------|---------|
+| `bluebird` | >= 3.7.0 |
+| `dayjs` | ^1.11.13 |
+| `lodash` | >= 4.17.15 |
+| `sequelize` | >= 6.6.2 |
+| `umzug` | >= 3.2.1 |
+
+## Testing
+
+```bash
+npm test                # unit tests (BUILD_ENV=test)
+npm run itest           # integration tests (BUILD_ENV=development)
+```
+
+Tests use Jasmine 5 with NYC coverage. Coverage thresholds: branches >= 70%, functions >= 70%, statements >= 85%, lines >= 80%.
+
+## License
+
+Private - Copyright (c) Piper