@markwharton/pwa-core 2.0.0 → 3.0.0

package/dist/server.d.ts

@@ -8,13 +8,27 @@ import { TableClient } from '@azure/data-tables';
 import { Result, BaseJwtPayload, RoleTokenPayload } from './shared';
 /**
  * Initializes the JWT authentication system. Call once at application startup.
- * @param secret - The JWT secret key (from environment variable)
- * @param minLength - Minimum required secret length (default: 32)
+ * @param config - Configuration object
+ * @param config.secret - The JWT secret key (from environment variable)
+ * @param config.minLength - Minimum required secret length (default: 32)
  * @throws Error if secret is missing or too short
  * @example
- * initAuth(process.env.JWT_SECRET);
+ * initAuth({ secret: process.env.JWT_SECRET });
+ * initAuth({ secret: process.env.JWT_SECRET, minLength: 64 });
  */
-export declare function initAuth(secret: string | undefined, minLength?: number): void;
+export declare function initAuth(config: {
+    secret?: string;
+    minLength?: number;
+}): void;
+/**
+ * Initializes JWT authentication from environment variables.
+ * Reads JWT_SECRET from process.env.
+ * @param minLength - Minimum required secret length (default: 32)
+ * @throws Error if JWT_SECRET is missing or too short
+ * @example
+ * initAuthFromEnv(); // Uses process.env.JWT_SECRET
+ */
+export declare function initAuthFromEnv(minLength?: number): void;
 /**
  * Gets the configured JWT secret.
  * @returns The JWT secret string
@@ -186,20 +200,62 @@ export declare function notFoundResponse(resource: string): HttpResponseInit;
  * if (existingUser) return conflictResponse('Email already registered');
  */
 export declare function conflictResponse(message: string): HttpResponseInit;
+/**
+ * Validates that a required parameter is present.
+ * Returns an error response if missing, null if valid.
+ * @param value - The value to check
+ * @param paramName - The parameter name for the error message
+ * @returns HttpResponseInit if invalid, null if valid
+ * @example
+ * const error = validateRequired(userId, 'userId');
+ * if (error) return error;
+ * // userId is guaranteed to be defined here
+ */
+export declare function validateRequired(value: string | undefined, paramName: string): HttpResponseInit | null;
+/**
+ * Callback type for error handling hooks (e.g., alerting, monitoring).
+ */
+export type ErrorCallback = (operation: string, message: string) => void;
+/**
+ * Sets a callback to be invoked when handleFunctionError is called.
+ * Use this to integrate with alerting or monitoring systems.
+ * @param callback - The callback to invoke (fire-and-forget)
+ * @example
+ * setErrorCallback((operation, message) => {
+ *   sendAlert(operation, message); // Fire-and-forget
+ * });
+ */
+export declare function setErrorCallback(callback: ErrorCallback | null): void;
 /**
  * Handles unexpected errors safely by logging details and returning a generic message.
  * Use in catch blocks to avoid exposing internal error details to clients.
  * @param error - The caught error
  * @param context - Azure Functions InvocationContext for logging
+ * @param operation - Optional operation name for error callback
  * @returns Azure Functions HttpResponseInit with 500 status
  * @example
  * try {
  *   await riskyOperation();
  * } catch (error) {
- *   return handleFunctionError(error, context);
+ *   return handleFunctionError(error, context, 'riskyOperation');
  * }
  */
-export declare function handleFunctionError(error: unknown, context: InvocationContext): HttpResponseInit;
+export declare function handleFunctionError(error: unknown, context: InvocationContext, operation?: string): HttpResponseInit;
+/**
+ * Checks if an error is an Azure Table Storage error with a specific status code.
+ * @param error - The caught error
+ * @param statusCode - The HTTP status code to check for
+ * @returns True if error has the specified statusCode
+ * @example
+ * try {
+ *   await tableClient.upsertEntity(entity);
+ * } catch (error) {
+ *   if (isTableStorageError(error, 412)) {
+ *     // Precondition failed - ETag mismatch
+ *   }
+ * }
+ */
+export declare function isTableStorageError(error: unknown, statusCode: number): boolean;
 /**
  * Checks if an error is an Azure Table Storage "not found" error.
  * @param error - The caught error
@@ -273,6 +329,20 @@ export declare function getTableClient(tableName: string): Promise<TableClient>;
  * });
  */
 export declare function clearTableClientCache(): void;
+/**
+ * Gets an entity from Azure Table Storage if it exists, or returns null.
+ * Eliminates the common try-catch-isNotFoundError pattern.
+ * @typeParam T - The entity type (extends object)
+ * @param client - The TableClient instance
+ * @param partitionKey - The partition key
+ * @param rowKey - The row key
+ * @returns The entity if found, null if not found
+ * @throws Re-throws non-404 errors
+ * @example
+ * const user = await getEntityIfExists<UserEntity>(client, 'users', id);
+ * if (!user) return notFoundResponse('User');
+ */
+export declare function getEntityIfExists<T extends object>(client: TableClient, partitionKey: string, rowKey: string): Promise<T | null>;
 /**
  * Generate a unique row key from an identifier string.
  * Uses SHA-256 hash for consistent, URL-safe keys.

package/dist/server.js

@@ -10,6 +10,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HTTP_STATUS = exports.isAdmin = exports.hasRole = exports.hasUsername = exports.getErrorMessage = exports.err = exports.okVoid = exports.ok = exports.DEFAULT_TOKEN_EXPIRY_SECONDS = exports.DEFAULT_TOKEN_EXPIRY = void 0;
 exports.initAuth = initAuth;
+exports.initAuthFromEnv = initAuthFromEnv;
 exports.getJwtSecret = getJwtSecret;
 exports.extractToken = extractToken;
 exports.validateToken = validateToken;
@@ -26,7 +27,10 @@ exports.unauthorizedResponse = unauthorizedResponse;
 exports.forbiddenResponse = forbiddenResponse;
 exports.notFoundResponse = notFoundResponse;
 exports.conflictResponse = conflictResponse;
+exports.validateRequired = validateRequired;
+exports.setErrorCallback = setErrorCallback;
 exports.handleFunctionError = handleFunctionError;
+exports.isTableStorageError = isTableStorageError;
 exports.isNotFoundError = isNotFoundError;
 exports.isConflictError = isConflictError;
 exports.initStorage = initStorage;
@@ -34,6 +38,7 @@ exports.initStorageFromEnv = initStorageFromEnv;
 exports.useManagedIdentity = useManagedIdentity;
 exports.getTableClient = getTableClient;
 exports.clearTableClientCache = clearTableClientCache;
+exports.getEntityIfExists = getEntityIfExists;
 exports.generateRowKey = generateRowKey;
 const crypto_1 = require("crypto");
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
@@ -46,18 +51,35 @@ const shared_1 = require("./shared");
 let jwtSecret = null;
 /**
  * Initializes the JWT authentication system. Call once at application startup.
- * @param secret - The JWT secret key (from environment variable)
- * @param minLength - Minimum required secret length (default: 32)
+ * @param config - Configuration object
+ * @param config.secret - The JWT secret key (from environment variable)
+ * @param config.minLength - Minimum required secret length (default: 32)
  * @throws Error if secret is missing or too short
  * @example
- * initAuth(process.env.JWT_SECRET);
+ * initAuth({ secret: process.env.JWT_SECRET });
+ * initAuth({ secret: process.env.JWT_SECRET, minLength: 64 });
  */
-function initAuth(secret, minLength = 32) {
+function initAuth(config) {
+    const { secret, minLength = 32 } = config;
     if (!secret || secret.length < minLength) {
         throw new Error(`JWT_SECRET must be at least ${minLength} characters`);
     }
     jwtSecret = secret;
 }
+/**
+ * Initializes JWT authentication from environment variables.
+ * Reads JWT_SECRET from process.env.
+ * @param minLength - Minimum required secret length (default: 32)
+ * @throws Error if JWT_SECRET is missing or too short
+ * @example
+ * initAuthFromEnv(); // Uses process.env.JWT_SECRET
+ */
+function initAuthFromEnv(minLength = 32) {
+    initAuth({
+        secret: process.env.JWT_SECRET,
+        minLength
+    });
+}
 /**
  * Gets the configured JWT secret.
  * @returns The JWT secret string
@@ -300,27 +322,86 @@ function conflictResponse(message) {
         jsonBody: { error: message }
     };
 }
+/**
+ * Validates that a required parameter is present.
+ * Returns an error response if missing, null if valid.
+ * @param value - The value to check
+ * @param paramName - The parameter name for the error message
+ * @returns HttpResponseInit if invalid, null if valid
+ * @example
+ * const error = validateRequired(userId, 'userId');
+ * if (error) return error;
+ * // userId is guaranteed to be defined here
+ */
+function validateRequired(value, paramName) {
+    if (!value) {
+        return badRequestResponse(`${paramName} is required`);
+    }
+    return null;
+}
+let errorCallback = null;
+/**
+ * Sets a callback to be invoked when handleFunctionError is called.
+ * Use this to integrate with alerting or monitoring systems.
+ * @param callback - The callback to invoke (fire-and-forget)
+ * @example
+ * setErrorCallback((operation, message) => {
+ *   sendAlert(operation, message); // Fire-and-forget
+ * });
+ */
+function setErrorCallback(callback) {
+    errorCallback = callback;
+}
 /**
  * Handles unexpected errors safely by logging details and returning a generic message.
  * Use in catch blocks to avoid exposing internal error details to clients.
  * @param error - The caught error
  * @param context - Azure Functions InvocationContext for logging
+ * @param operation - Optional operation name for error callback
  * @returns Azure Functions HttpResponseInit with 500 status
  * @example
  * try {
  *   await riskyOperation();
  * } catch (error) {
- *   return handleFunctionError(error, context);
+ *   return handleFunctionError(error, context, 'riskyOperation');
  * }
  */
-function handleFunctionError(error, context) {
+function handleFunctionError(error, context, operation) {
     const message = error instanceof Error ? error.message : 'Unknown error';
     context.error(`Function error: ${message}`);
+    // Fire-and-forget callback (for alerting, monitoring)
+    if (errorCallback && operation) {
+        try {
+            errorCallback(operation, message);
+        }
+        catch {
+            // Swallow callback errors to prevent cascading failures
+        }
+    }
     return {
         status: shared_1.HTTP_STATUS.INTERNAL_ERROR,
         jsonBody: { error: 'Internal server error' }
     };
 }
+/**
+ * Checks if an error is an Azure Table Storage error with a specific status code.
+ * @param error - The caught error
+ * @param statusCode - The HTTP status code to check for
+ * @returns True if error has the specified statusCode
+ * @example
+ * try {
+ *   await tableClient.upsertEntity(entity);
+ * } catch (error) {
+ *   if (isTableStorageError(error, 412)) {
+ *     // Precondition failed - ETag mismatch
+ *   }
+ * }
+ */
+function isTableStorageError(error, statusCode) {
+    return (error instanceof Error &&
+        'statusCode' in error &&
+        error.statusCode === statusCode);
+}
 /**
  * Checks if an error is an Azure Table Storage "not found" error.
  * @param error - The caught error
@@ -334,9 +415,7 @@ function handleFunctionError(error, context) {
  * }
  */
 function isNotFoundError(error) {
-    return (error instanceof Error &&
-        'statusCode' in error &&
-        error.statusCode === 404);
+    return isTableStorageError(error, shared_1.HTTP_STATUS.NOT_FOUND);
 }
 /**
  * Checks if an error is an Azure Table Storage "conflict" error.
@@ -351,15 +430,21 @@ function isNotFoundError(error) {
  * }
  */
 function isConflictError(error) {
-    return (error instanceof Error &&
-        'statusCode' in error &&
-        error.statusCode === 409);
+    return isTableStorageError(error, shared_1.HTTP_STATUS.CONFLICT);
 }
 // =============================================================================
 // Azure Table Storage
 // =============================================================================
 // Cache table clients to avoid repeated connections
 const tableClients = new Map();
+// Shared credential instance for managed identity (avoids repeated instantiation)
+let credential = null;
+function getCredential() {
+    if (!credential) {
+        credential = new identity_1.DefaultAzureCredential();
+    }
+    return credential;
+}
 // Configuration
 let storageAccountName;
 let storageConnectionString;
@@ -416,10 +501,9 @@ async function getTableClient(tableName) {
     }
     let client;
     if (useManagedIdentity()) {
-        // Azure: Use managed identity
-        const credential = new identity_1.DefaultAzureCredential();
+        // Azure: Use managed identity (credential is cached)
         const endpoint = `https://${storageAccountName}.table.core.windows.net`;
-        client = new data_tables_1.TableClient(endpoint, tableName, credential);
+        client = new data_tables_1.TableClient(endpoint, tableName, getCredential());
     }
     else if (storageConnectionString) {
         // Local/Azurite: Use connection string
@@ -453,6 +537,30 @@ async function getTableClient(tableName) {
 function clearTableClientCache() {
     tableClients.clear();
 }
+/**
+ * Gets an entity from Azure Table Storage if it exists, or returns null.
+ * Eliminates the common try-catch-isNotFoundError pattern.
+ * @typeParam T - The entity type (extends object)
+ * @param client - The TableClient instance
+ * @param partitionKey - The partition key
+ * @param rowKey - The row key
+ * @returns The entity if found, null if not found
+ * @throws Re-throws non-404 errors
+ * @example
+ * const user = await getEntityIfExists<UserEntity>(client, 'users', id);
+ * if (!user) return notFoundResponse('User');
+ */
+async function getEntityIfExists(client, partitionKey, rowKey) {
+    try {
+        return await client.getEntity(partitionKey, rowKey);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
 /**
  * Generate a unique row key from an identifier string.
  * Uses SHA-256 hash for consistent, URL-safe keys.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/pwa-core",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Shared patterns for Azure PWA projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",