@churchapps/apihelper 0.5.2 → 0.5.3

package/package.json

@@ -1,66 +1,64 @@
-{
-  "name": "@churchapps/apihelper",
-  "version": "0.5.2",
-  "description": "Library of helper functions not specific to any one ChurchApps project or framework.",
-  "type": "module",
-  "main": "dist/index.js",
-  "exports": {
-    ".": "./dist/index.js",
-    "./helpers": "./dist/helpers/index.js",
-    "./auth": "./dist/auth/index.js", 
-    "./controllers": "./dist/controllers/index.js"
-  },
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "clean": "rimraf dist",
-    "copy-assets": "node scripts/copy-assets.js",
-    "link": "link",
-    "tsc": "tsc",
-    "build": "npm-run-all clean tsc copy-assets",
-    "lint": "eslint src/**/*.ts",
-    "lint:fix": "eslint src/**/*.ts --fix",
-    "format": "prettier --write src/**/*.ts",
-    "format:check": "prettier --check src/**/*.ts",
-    "publish:all": "npm run build && npm publish --access=public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ChurchApps/ApiHelper.git"
-  },
-  "keywords": [
-    "ChurchApps"
-  ],
-  "author": "ChurchApps.org",
-  "license": "MIT",
-  "dependencies": {
-    "@aws-sdk/client-s3": "^3.862.0",
-    "@aws-sdk/client-ses": "^3.862.0",
-    "@aws-sdk/client-ssm": "^3.862.0",
-    "@aws-sdk/s3-presigned-post": "^3.862.0",
-    "@churchapps/helpers": "^1.2.19",
-    "dotenv": "^17.2.1",
-    "express": "^4.21.2",
-    "inversify": "^6.2.2",
-    "inversify-express-utils": "^6.5.0",
-    "jsonwebtoken": "^9.0.2",
-    "mysql2": "^3.14.3",
-    "nodemailer": "^7.0.5",
-    "winston": "^3.17.0",
-    "winston-cloudwatch": "^6.3.0"
-  },
-  "devDependencies": {
-    "@types/express": "^4.17.21",
-    "@types/jsonwebtoken": "^9.0.10",
-    "@types/node": "^24.2.0",
-    "@types/nodemailer": "^6.4.17",
-    "@typescript-eslint/eslint-plugin": "^8.39.0",
-    "@typescript-eslint/parser": "^8.39.0",
-    "eslint": "^9.32.0",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.4",
-    "npm-run-all2": "^8.0.4",
-    "prettier": "^3.6.2",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.9.2"
-  }
-}
+{
+  "name": "@churchapps/apihelper",
+  "version": "0.5.3",
+  "description": "Library of helper functions not specific to any one ChurchApps project or framework.",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./helpers": "./dist/helpers/index.js",
+    "./auth": "./dist/auth/index.js",
+    "./controllers": "./dist/controllers/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "clean": "rimraf dist",
+    "copy-assets": "node scripts/copy-assets.js",
+    "link": "link",
+    "tsc": "tsc",
+    "build": "npm-run-all clean tsc copy-assets",
+    "lint": "eslint --fix src/",
+    "publish:all": "npm run build && npm publish --access=public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChurchApps/ApiHelper.git"
+  },
+  "keywords": [
+    "ChurchApps"
+  ],
+  "author": "ChurchApps.org",
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.862.0",
+    "@aws-sdk/client-ses": "^3.862.0",
+    "@aws-sdk/client-ssm": "^3.862.0",
+    "@aws-sdk/s3-presigned-post": "^3.862.0",
+    "@churchapps/helpers": "^1.2.19",
+    "dotenv": "^17.2.1",
+    "express": "^4.21.2",
+    "inversify": "^6.2.2",
+    "inversify-express-utils": "^6.5.0",
+    "jsonwebtoken": "^9.0.2",
+    "mysql2": "^3.14.3",
+    "nodemailer": "^7.0.5",
+    "winston": "^3.17.0",
+    "winston-cloudwatch": "^6.3.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^24.2.0",
+    "@types/nodemailer": "^6.4.17",
+    "@typescript-eslint/eslint-plugin": "^8.39.0",
+    "@typescript-eslint/parser": "^8.39.0",
+    "eslint": "^9.32.0",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "npm-run-all2": "^8.0.4",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.2"
+  }
+}

package/.github/FUNDING.yml

@@ -1 +0,0 @@
-github: [ChurchApps]

package/.prettierrc.json

@@ -1,13 +0,0 @@
-{
-  "printWidth": 120,
-  "tabWidth": 2,
-  "useTabs": false,
-  "semi": true,
-  "singleQuote": false,
-  "quoteProps": "as-needed",
-  "trailingComma": "none",
-  "bracketSpacing": true,
-  "bracketSameLine": false,
-  "arrowParens": "avoid",
-  "endOfLine": "lf"
-}

package/CLAUDE.md

@@ -1,110 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-This is the `@churchapps/apihelper` package - a Node.js/Express.js server-side utility library that provides common functionality for ChurchApps API projects. It serves as a foundation layer for building REST APIs with authentication, database access, AWS integration, and error handling.
-
-## Key Dependencies
-
-- **Core**: Express.js with Inversify for dependency injection
-- **AWS SDK v3**: S3, SES, CloudWatch Logs, SSM Parameter Store
-- **Database**: MySQL2 with connection pooling
-- **Authentication**: JSON Web Tokens (JWT)
-- **Depends on**: `@churchapps/helpers` (base utilities package)
-
-## Common Development Commands
-
-```bash
-# Build the package
-npm run clean      # Remove dist folder
-npm run tsc        # TypeScript compilation only  
-npm run build      # Full build (clean + tsc + copy-assets)
-
-# Code quality
-npm run lint       # Run ESLint
-npm run lint:fix   # Auto-fix lint issues
-npm run format     # Format code with Prettier
-npm run format:check # Check formatting
-
-# Local development
-npm run build
-npm link
-
-# In consuming project
-npm link @churchapps/apihelper
-
-# Publishing
-npm run build
-npm publish --access=public
-```
-
-## Architecture Overview
-
-### Core Components
-
-1. **Authentication System** (`/auth`)
-   - `CustomAuthProvider`: Inversify-based authentication provider
-   - `AuthenticatedUser`: User session management with JWT
-   - `Principal`: Security principal for authorization checks
-
-2. **Base Controllers** (`/controllers`)
-   - `CustomBaseController`: Extends Inversify's BaseHttpController
-     - Provides error handling (`internalServerError`, `notFound`, `conflict`)
-     - Authentication helpers (`loadUser`, `checkAccess`)
-     - Request utilities (`getNumber`, `getBoolean`, `getDate`)
-   - `ErrorController`: Centralized error logging to database
-
-3. **AWS Integration** (`/helpers`)
-   - `AwsHelper`: S3 operations, SSM parameter reading, presigned URLs
-   - `FileStorageHelper`: Abstraction for file storage operations
-   - `EmailHelper`: Dual support for SMTP and AWS SES
-   - `LoggingHelper`: Winston logging with CloudWatch integration
-
-4. **Database Layer** (`/helpers`)
-   - `DB`: Promise-based MySQL query wrapper
-   - `Pool`: MySQL connection pooling management
-   - `MySqlHelper`: MySQL-specific utilities
-   - `DBCreator`: Database schema creation utilities
-
-### Key Technical Details
-
-- **Inversify Decorators**: Controllers use `@controller`, `@httpGet`, etc.
-- **Environment Configuration**: `EnvironmentBase` class handles env vars with SSM fallback
-- **Email Templates**: HTML templates copied to dist/templates during build
-- **TypeScript**: Targets ES2020 with decorators enabled, declaration files generated
-
-### Important Notes
-
-- **Build Process Issue**: The copy-assets script references `src/apiBase/tools/templates/*` but the actual path is `src/tools/templates/*`
-- **No Test Suite**: Currently no tests configured in package.json
-- **Environment Variables**: Expects `CONNECTION_STRING`, `ENCRYPTION_KEY`, `JWT_SECRET`, `SMTP_*` configs
-
-## Usage Pattern
-
-This package is designed to be extended by API projects:
-
-```typescript
-// Example controller
-import { controller, httpGet } from "inversify-express-utils";
-import { CustomBaseController } from "@churchapps/apihelper";
-
-@controller("/api/example")
-export class ExampleController extends CustomBaseController {
-    @httpGet("/")
-    public async getAll(req: express.Request, res: express.Response): Promise<any> {
-        return this.actionWrapper(req, res, async () => {
-            // Implementation
-        });
-    }
-}
-```
-
-## Development Workflow
-
-1. Controllers extend `CustomBaseController` for built-in error handling and utilities
-2. Use `EnvironmentBase` for configuration management
-3. Database queries through `DB.query()` or `DB.queryOne()`
-4. AWS operations via `AwsHelper` static methods
-5. Logging through `LoggingHelper.getInstance()` singleton

package/eslint.config.mjs

@@ -1,40 +0,0 @@
-import eslint from "@eslint/js";
-import tseslint from "@typescript-eslint/eslint-plugin";
-import parser from "@typescript-eslint/parser";
-
-export default [
-  eslint.configs.recommended,
-  {
-    files: ["**/*.ts"],
-    languageOptions: {
-      parser: parser,
-      parserOptions: {
-        ecmaVersion: 2020,
-        sourceType: "module"
-      },
-      globals: {
-        console: "readonly",
-        process: "readonly",
-        Buffer: "readonly",
-        __dirname: "readonly",
-        global: "readonly"
-      }
-    },
-    plugins: {
-      "@typescript-eslint": tseslint
-    },
-    rules: {
-      "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }],
-      "no-unused-vars": ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }],
-      "@typescript-eslint/no-explicit-any": "warn",
-      "no-console": "off",
-      "no-useless-catch": "off",
-      "comma-dangle": ["error", "never"],
-      "object-curly-spacing": ["error", "always"],
-      "array-bracket-spacing": ["error", "never"]
-    }
-  },
-  {
-    ignores: ["dist/**/*", "node_modules/**/*"]
-  }
-];

package/scripts/copy-assets.js

@@ -1,35 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-async function copyAssets() {
-  try {
-    const srcDir = path.join(__dirname, '..', 'src', 'tools', 'templates');
-    const destDir = path.join(__dirname, '..', 'dist', 'templates');
-    
-    // Ensure destination directory exists
-    await fs.promises.mkdir(destDir, { recursive: true });
-    
-    // Copy all files from src/tools/templates to dist/templates
-    const files = await fs.promises.readdir(srcDir);
-    for (const file of files) {
-      const srcPath = path.join(srcDir, file);
-      const destPath = path.join(destDir, file);
-      const stat = await fs.promises.stat(srcPath);
-      
-      if (stat.isFile()) {
-        await fs.promises.copyFile(srcPath, destPath);
-      }
-    }
-    
-    console.log('Assets copied successfully');
-  } catch (error) {
-    console.error('Error copying assets:', error);
-    process.exit(1);
-  }
-}
-
-copyAssets();

package/src/auth/AuthenticatedUser.ts

@@ -1,44 +0,0 @@
-import { Principal } from "./Principal.js";
-import { IPermission } from "../helpers/Interfaces.js";
-
-export class AuthenticatedUser {
-  public id: string;
-  public churchId: string;
-  public email: string;
-  public apiName: string;
-  public permissions: string[];
-  public personId: string;
-  public firstName: string;
-  public lastName: string;
-  public membershipStatus?: string;
-  public groupIds?: string[];
-  public leaderGroupIds?: string[]; 
-  public jwt: string;
-
-  public constructor(principal: Principal) {
-    this.jwt = principal.details.jwt || "";
-    this.id = principal.details.id || "";
-    this.churchId = principal.details.churchId || "";
-    this.permissions = principal.details.permissions || [];
-    this.apiName = principal.details.apiName || "";
-    this.email = principal.details.email || "";
-    this.personId = principal.details.personId || "";
-    this.firstName = principal.details.firstName || "";
-    this.lastName = principal.details.lastName || "";
-    this.membershipStatus = principal.details.membershipStatus;
-    this.groupIds = principal.details.groupIds || [];
-    this.leaderGroupIds = principal.details.leaderGroupIds || [];
-  }
-
-  public checkAccess(permission: IPermission) {
-    const key = (permission.apiName)
-      ? permission.apiName + "_" + permission.contentType + "__" + permission.action
-      : permission.contentType + "__" + permission.action;
-
-    let result = false;
-    this.permissions?.forEach((p: string) => {
-      if (p === key) result = true;
-    });
-    return result;
-  }
-}

package/src/auth/CustomAuthProvider.ts

@@ -1,25 +0,0 @@
-import { injectable } from "inversify";
-import { interfaces } from "inversify-express-utils";
-import express from "express";
-import jwt from "jsonwebtoken";
-import { Principal } from "./Principal.js";
-import { EnvironmentBase } from "../helpers/EnvironmentBase.js";
-
-@injectable()
-export class CustomAuthProvider implements interfaces.AuthProvider {
-  // public async getUser(req: express.Request, res: express.Response, next: express.NextFunction): Promise<interfaces.Principal> {
-  public async getUser(req: express.Request, _res: express.Response, _next: express.NextFunction): Promise<Principal> {
-    const authHeader = req.headers.authorization;
-    if (authHeader) {
-      const token = authHeader.split(" ")[1];
-      if (!token) return null;
-      const decoded = jwt.verify(token, EnvironmentBase.jwtSecret);
-
-      const result = decoded ? new Principal(typeof decoded === 'object' && decoded !== null ? decoded as Record<string, unknown> : {}) : null;
-      if (result) result.details.jwt = token;
-      return result;
-    }
-
-    return null;
-  }
-}

package/src/auth/Principal.ts

@@ -1,38 +0,0 @@
-import { interfaces } from "inversify-express-utils";
-
-export interface PrincipalDetails {
-  jwt?: string;
-  id?: string;
-  churchId?: string;
-  permissions?: string[];
-  apiName?: string;
-  email?: string;
-  personId?: string;
-  firstName?: string;
-  lastName?: string;
-  membershipStatus?: string;
-  groupIds?: string[];
-  leaderGroupIds?: string[];
-  [key: string]: unknown;
-}
-
-export class Principal implements interfaces.Principal {
-  public details: PrincipalDetails;
-
-  public constructor(details: PrincipalDetails) {
-    this.details = details;
-  }
-
-  public isAuthenticated(): Promise<boolean> {
-    return Promise.resolve(true);
-  }
-
-  public isResourceOwner(resourceId: string | number): Promise<boolean> {
-    return Promise.resolve(resourceId === 1111);
-  }
-
-  public isInRole(role: string): Promise<boolean> {
-    return Promise.resolve(role === "admin");
-  }
-
-}

package/src/auth/index.ts

@@ -1,3 +0,0 @@
-export { AuthenticatedUser } from "./AuthenticatedUser.js";
-export { CustomAuthProvider } from "./CustomAuthProvider.js";
-export { Principal } from "./Principal.js";

package/src/controllers/CustomBaseController.ts

@@ -1,62 +0,0 @@
-import { BaseHttpController } from "inversify-express-utils";
-import express from "express";
-import { LoggingHelper } from "../helpers/LoggingHelper.js";
-import { AuthenticatedUser, Principal } from "../auth/index.js";
-
-export class CustomBaseController extends BaseHttpController {
-
-    public logger: LoggingHelper;
-
-    constructor() {
-        super()
-        this.logger = LoggingHelper.getCurrent();
-    }
-
-    public error(errors: string[]) {
-        return this.json({ errors }, 500);
-    }
-
-    public denyAccess(errors: string[]) {
-        return this.json({ errors }, 401);
-    }
-
-    public authUser(): AuthenticatedUser {
-        if (this.httpContext.user === null) return new AuthenticatedUser(new Principal({}));
-        else return new AuthenticatedUser(this.httpContext.user as Principal);
-    }
-
-    public include(req: express.Request, item: string) {
-        let result = false;
-        if (req.query.include !== undefined) {
-            const value: string = req.query.include as string;
-            const items = value.split(",");
-            if (items.indexOf(item) > -1) result = true;
-        }
-        return result;
-    }
-
-    public async actionWrapper(_req: express.Request, _res: express.Response, fetchFunction: (_au: AuthenticatedUser) => unknown): Promise<unknown> {
-        try {
-            const result = await fetchFunction(this.authUser());
-            await this.logger.flush();
-            return result;
-        } catch (e: unknown) {
-            // Since logger.error now throws, just re-throw the error
-            throw e;
-        }
-    }
-
-    public async actionWrapperAnon(_req: express.Request, _res: express.Response, fetchFunction: () => unknown): Promise<unknown> {
-        try {
-            const result = await fetchFunction();
-            await this.logger.flush();
-            return result;
-        } catch (e: unknown) {
-            // Since logger.error now throws, just re-throw the error
-            throw e;
-        }
-    }
-
-
-
-}

package/src/controllers/ErrorController.ts

@@ -1,33 +0,0 @@
-import { controller, httpPost } from "inversify-express-utils";
-import express from "express";
-import { CustomBaseController } from "./CustomBaseController.js";
-import { ErrorLog } from "../models/index.js";
-
-
-@controller("/errors")
-export class ErrorController extends CustomBaseController {
-
-    @httpPost("/")
-    public async save(req: express.Request<{}, {}, ErrorLog[]>, _res: express.Response): Promise<ErrorLog[]> {
-        // try {
-        /*
-        try {
-            au = this.authUser();
-        } catch (e) {
-            this.logger.log(req.body[0].application, "info", e);
-        }*/
-        req.body.forEach(error => {
-            let fullMessage = error.message;
-            if (error.additionalDetails !== undefined) fullMessage += "\n" + error.additionalDetails;
-            // if (au !== null) fullMessage += "\nUser: " + au.id + " Church: " + au.churchId;
-            this.logger.log(error.application, error.level, fullMessage);
-        });
-        await this.logger.flush();
-        return req.body;
-        // } catch (e) {
-        // console.log(e)
-        // };
-
-    }
-
-}

package/src/controllers/index.ts

@@ -1,2 +0,0 @@
-export { CustomBaseController } from "./CustomBaseController.js";
-export { ErrorController } from "./ErrorController.js";