piper-utils 1.1.62 → 1.1.63

package/CLAUDE.md

@@ -1,5 +1,107 @@
 # CLAUDE.md
 
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
 ## Forbidden Cognito Operations
 
 NEVER use `UpdateUserPoolClient` or `DescribeUserPoolClient` from the AWS Cognito SDK or AWS CLI. The `UpdateUserPoolClient` API is a full replacement — any omitted property resets to its default. This has caused production outages twice (March 4 and March 17, 2026) by wiping `ExplicitAuthFlows` (removing `ALLOW_USER_SRP_AUTH`) and `ReadAttributes` from both dev and prod app clients. Cognito app client configuration must only be managed via the AWS Console (where all fields are visible) or via IaC that specifies every property.
+
+## Build & Test Commands
+
+```bash
+npm test              # Unit tests (BUILD_ENV=test) with NYC coverage
+npm run itest         # Integration tests (BUILD_ENV=development)
+npm run build         # Dev build via webpack -> bin/main.js
+npm run build-prod    # Production build (BUILD_ENV=production, minified)
+```
+
+Run a single test file by passing `--filter`:
+```bash
+npx cross-env BUILD_ENV='test' nyc jasmine JASMINE_CONFIG_PATH=jasmine.json --filter="**/accessRightsUtils.test*"
+```
+
+Tests use **Jasmine 5** with **NYC** coverage. Coverage thresholds: branches ≥ 70%, functions ≥ 70%, statements ≥ 85%, lines ≥ 80%. Test files live next to their source files as `*.test.js`.
+
+## Architecture
+
+This is a shared utility library (`piper-utils`) consumed by AWS Lambda microservices via npm. It is built with Babel (targeting Node 22) and bundled with webpack into `bin/main.js` (CommonJS output).
+
+### Source Layout (`src/`)
+
+- **`index.js`** — Single barrel export file. Every public function is re-exported here. Internal modules (S3Utils, SNSUtils, dynamoUtils) are NOT exported.
+- **`requestResponse/`** — API Gateway Lambda proxy response formatting (`success`, `failure`, `successHtml`, `parseBody`, `parseEvent`, `getCurrentUser`). Includes security headers (HSTS, CSP, etc.) and auto-detection of Joi/Sequelize/Dynamoose errors in `failure()`.
+- **`database/dbUtils/queryStringUtils/`** — Core query DSL translating API query strings into Sequelize queries:
+  - `defaultFilters.js` — Maps Sequelize column types to operators (iLike for strings, Op.between for dates, etc.)
+  - `createFilters.js` — Builds WHERE clauses with automatic business ID scoping, active-record filtering, date ranges, and full-text search
+  - `createSort.js` — Converts `sort` query param to ORDER BY arrays
+  - `createIncludes.js` — Auto-detects relation includes from dot-notation in filters/sort
+  - `findAll.js` — Paginated findAll (fetches limit+1 to detect `hasMore`)
+  - `accessRightsUtils.js` — All auth/access control functions (accessRightsUtils, checkWriteAccess, checkModule, checkIsSuper, isSuperUser, isSystemUser, partner functions, getCompanySettings). Reads JWT claims from `event.requestContext.authorizer.claims`.
+- **`database/dbSetUp/migrations.js`** — Umzug-based migration runner with auto-rollback on failure.
+- **`eventManager/`** — S3 file processing pipeline: `watchBucket` routes events (SNS/S3/cron) → `publishEvents` scans S3 and publishes file batches to SNS → `handleEvents` processes files in parallel via `handleFile`. Failed files move through `failed-once/` → `failed-twice/` → `error/` retry folders.
+- **`s3/S3Utils/`**, **`sns/SNSUtils.js`**, **`dynamo/dynamoUtils.js`** — Internal AWS SDK v3 wrappers (not publicly exported).
+
+### Key Design Patterns
+
+- **`BUILD_ENV` gating**: Auth checks are relaxed when `BUILD_ENV=local` (injects default business ID `'1'` with admin access). Tests use `BUILD_ENV=test`.
+- **Synchronous access control**: All access control functions are synchronous (read JWT claims from the event). The `enrichEventWithPartnerAccess` function mutates the event in-memory before calling sync auth functions — this avoids making the entire auth stack async.
+- **Error convention**: Errors are plain objects with `{ statusCode, errorCode, message }`. Built-in error codes are in `requestResponse/errorCodes.js`. The `failure()` function auto-detects error types (Joi, Sequelize, etc.) and formats them.
+
+## CI
+
+Bitbucket Pipelines runs `npm test` on the `master` branch using a Node 22 image (`kevinlbatchelor/flow-22`).
+
+## Peer Dependencies
+
+Consuming projects must provide: `bluebird` (≥3.7.0), `dayjs` (^1.11.13), `lodash` (≥4.17.15), `sequelize` (≥6.6.2), `umzug` (≥3.2.1).
+
+## Testing Guidelines
+
+### Spy rules — only mock external boundaries
+
+**DO spy on:** database model methods (`Model.findOne`, `Model.create`, `Model.findAll`, `Model.update`, `Model.destroy`), HTTP calls (`axios.get/post/put`), AWS SDK clients (S3, SNS), and external services.
+
+**DO NOT spy on** auth/access functions (`checkModule`, `checkWriteAccess`, `accessRightsUtils`, `getCurrentUser`, `parseBody`, `createFilters`, `createSort`). Instead, build a proper mock event with `requestContext.authorizer.claims['custom:AR']`:
+
+```javascript
+const mockEvent = {
+    body: { /* ... */ },
+    pathParameters: { id: 1 },
+    queryStringParameters: { businessId: 'ABC' },
+    requestContext: {
+        authorizer: {
+            claims: {
+                'custom:AR': JSON.stringify({
+                    businessIds: { 'ABC': 'A' },
+                    module: { payment: { read: true, write: true } }
+                })
+            }
+        }
+    },
+    headers: { Authorization: 'Bearer mock-jwt-token' }
+};
+```
+
+### Test structure rules
+
+- **No `beforeEach`** — define all spies and setup inline within each `it()` block so tests are self-contained
+- **Inline spies per test** — each test creates its own spies, not shared across tests
+- Use `jasmine.createSpy()` for standalone function spies, `spyOn(obj, 'method')` for existing objects
+- Verify spy calls with `toHaveBeenCalledWith()` for important arguments
+
+### Spy patterns
+
+```javascript
+// Success
+spyOn(Model, 'findOne').and.returnValue(Promise.resolve(mockData));
+// Failure
+spyOn(Model, 'findOne').and.returnValue(Promise.reject(new Error('DB Error')));
+// Null/empty
+spyOn(Model, 'findOne').and.returnValue(Promise.resolve(null));
+```
+
+## Code Style
+
+- 4-space indentation, single quotes, trailing semicolons, no trailing commas
+- No `lodash.get` — use optional chaining instead
+- No nested ternaries — use if/else