@churchapps/apihelper 0.5.2 → 0.5.4

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";

package/src/helpers/AwsHelper.ts

@@ -1,129 +0,0 @@
-import { S3Client, GetObjectCommand, PutObjectCommand, DeleteObjectCommand, CopyObjectCommand, ListObjectsV2Command, ListObjectsV2Output } from "@aws-sdk/client-s3";
-import { createPresignedPost } from "@aws-sdk/s3-presigned-post";
-import { EnvironmentBase } from "./EnvironmentBase.js";
-import { SSMClient, GetParameterCommand } from "@aws-sdk/client-ssm";
-
-export class AwsHelper {
-
-  //Pulls from AWS SSM Parameter Store
-  static async readParameter(parameterName: string): Promise<string> {
-    let result = "";
-    try {
-      const ssm = new SSMClient({ region: "us-east-2" });
-      const params = { Name: parameterName, WithDecryption: true };
-      const command = new GetParameterCommand(params);
-      const response = await ssm.send(command);
-      result = response?.Parameter?.Value || "";
-    } catch {
-      result = "";
-    }
-    return result;
-  }
-
-
-  private static _client: S3Client;
-
-  private static getClient(): S3Client {
-    if (!this._client) {
-      this._client = new S3Client({});
-    }
-    return this._client;
-  }
-
-  static async S3PresignedUrl(key: string): Promise<{url: string, fields: Record<string, string>, key: string}> {
-    if (key.startsWith("/")) key = key.substring(1);
-    const { url, fields } = await createPresignedPost(this.getClient(), {
-      Bucket: EnvironmentBase.s3Bucket,
-      Key: key,
-      Conditions: [
-        ["starts-with", "$Content-Type", ""],
-        { acl: "public-read" }
-      ],
-      Expires: 3600 // 1 hour
-    });
-    return { url, fields, key };
-  }
-
-  static async S3Upload(key: string, contentType: string, contents: Buffer): Promise<void> {
-    if (key.startsWith("/")) key = key.substring(1);
-    const command = new PutObjectCommand({
-      Bucket: EnvironmentBase.s3Bucket,
-      Key: key,
-      Body: contents,
-      ACL: "public-read",
-      ContentType: contentType
-    });
-    await this.getClient().send(command);
-  }
-
-  static async S3Remove(key: string): Promise<void> {
-    if (key.startsWith("/")) key = key.substring(1);
-    const command = new DeleteObjectCommand({
-      Bucket: EnvironmentBase.s3Bucket,
-      Key: key
-    });
-    await this.getClient().send(command);
-  }
-
-  static async S3Rename(oldKey: string, newKey: string): Promise<void> {
-    console.log(`Renaming: ${oldKey} to ${newKey}`);
-    await this.S3Copy(oldKey, newKey);
-    await this.S3Remove(oldKey);
-  }
-
-  static S3Move(oldKey: string, newKey: string): Promise<void> {
-    return this.S3Rename(oldKey, newKey);
-  }
-
-  static async S3Copy(oldKey: string, newKey: string): Promise<void> {
-    const command = new CopyObjectCommand({
-      Bucket: EnvironmentBase.s3Bucket,
-      CopySource: `/${EnvironmentBase.s3Bucket}/${oldKey}`,
-      Key: newKey,
-      ACL: "public-read"
-    });
-    await this.getClient().send(command);
-  }
-
-  static async S3List(path: string): Promise<string[]> {
-    return this.S3ListMultiPage(this.getClient(), EnvironmentBase.s3Bucket, path);
-  }
-
-  static async S3ListMultiPage(s3:S3Client, bucket:string, path: string): Promise<string[]> {
-    const result: string[] = [];
-    let continuationToken: string | undefined;
-
-    do {
-      const { Contents, NextContinuationToken } = await this.S3ListManual(s3, bucket, path, continuationToken);
-      result.push(...(Contents?.map((item) => item.Key).filter((key): key is string => key !== undefined) || []));
-      continuationToken = NextContinuationToken;
-    } while (continuationToken);
-
-    return result;
-  }
-
-  private static async S3ListManual(s3:S3Client, bucket:string, path: string, continuationToken?: string): Promise<ListObjectsV2Output> {
-    const command = new ListObjectsV2Command({
-      Bucket: bucket,
-      Prefix: path,
-      MaxKeys: 10000,
-      ContinuationToken: continuationToken
-    });
-    return s3.send(command);
-  }
-
-  static async S3Read(key: string): Promise<string | null> {
-    try {
-      const command = new GetObjectCommand({
-        Bucket: EnvironmentBase.s3Bucket,
-        Key: key
-      });
-      const response = await this.getClient().send(command);
-      return await response.Body?.transformToString();
-    } catch (error) {
-      console.error("Error reading from S3:", error);
-      return null;
-    }
-  }
-
-}

package/src/helpers/BasePermissions.ts

@@ -1,15 +0,0 @@
-export class BasePermissions {
-  static forms = {
-    admin: { contentType: "Forms", action: "Admin" },
-    edit: { contentType: "Forms", action: "Edit" }
-  };
-  static links = {
-    edit: { contentType: "Links", action: "Edit" }
-  };
-  static pages = {
-    edit: { contentType: "Pages", action: "Edit" }
-  };
-  static settings = {
-    edit: { contentType: "Settings", action: "Edit" }
-  };
-}

package/src/helpers/DB.ts

@@ -1,41 +0,0 @@
-import { Pool } from "./Pool.js";
-import { PoolConnection, QueryError } from "mysql2";
-import { LoggingHelper } from "./LoggingHelper.js";
-
-export class DB {
-
-    // wraps in promise
-    static async getConnection() {
-        const promise: Promise<PoolConnection> = new Promise((resolve, reject) => {
-            Pool.current.getConnection((ex: QueryError | null, conn: PoolConnection) => { if (ex) reject(ex); else resolve(conn); });
-        });;
-        const connection: PoolConnection = await promise;
-        return connection;
-    }
-
-    // wraps in promise
-    static async getQuery(connection: PoolConnection, sql: string, params: unknown[]) {
-        const promise: Promise<unknown> = new Promise((resolve, reject) => {
-            connection.query(sql, params, async (ex: QueryError | null, rows: unknown) => {
-                if (ex) { LoggingHelper.getCurrent().error(ex); reject(ex); }
-                else { resolve(rows); }
-            });
-        });
-        const query: unknown = await promise;
-        return query;
-    }
-
-    public static async query(sql: string, params: unknown[]) {
-        let result: unknown = null;
-        const connection = await this.getConnection();
-        try { result = await this.getQuery(connection, sql, params); }
-        catch (ex: unknown) { LoggingHelper.getCurrent().error(ex as Error); }
-        finally { connection.release(); }
-        return result;
-    }
-
-    public static async queryOne(sql: string, params: unknown[]) {
-        const result = await this.query(sql, params) as unknown[];
-        return result?.length > 0 ? result[0] : null;
-    }
-}

package/src/helpers/DBCreator.ts

@@ -1,39 +0,0 @@
-import dotenv from "dotenv";
-import fs from "fs";
-import { DB } from "./DB.js";
-
-export class DBCreator {
-
-  private static tables: { title: string, file: string }[] = [
-    { title: "Links", file: "links.mysql" },
-    { title: "Pages", file: "pages.mysql" },
-    { title: "Settings", file: "settings.mysql" }
-  ]
-
-  public static async init(selectedTables: string[]) {
-    dotenv.config();
-
-    const todo: { title: string, file: string }[] = [];
-    selectedTables.forEach(async st => {
-      this.tables.forEach(async t => {
-        if (t.title === st) todo.push(t);
-      });
-    });
-
-    for (const td of todo) await this.runScript(td.title, "./src/tools/dbScripts/" + td.file, false);
-    return;
-  }
-
-  public static async runScript(title: string, file: string, customDelimeter: boolean) {
-    console.log("Creating '" + title + "'");
-    const sql = fs.readFileSync(file, "utf-8");
-    let del = /;(?=END)\s*$|;(?!\nEND)\s*$/gm;
-    if (customDelimeter) {
-      del = /\$\$$/gm;
-    }
-    const statements = sql.split(del);
-    for (const statement of statements) if (statement.length > 3) await DB.query(statement, []);
-  }
-
-
-}