@rxbenefits/server-utils 0.1.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@rxbenefits/server-utils",
+  "version": "0.1.0",
+  "private": false,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "axios": "^1.7.9",
+    "formidable": "^3.5.2",
+    "next": "^16.1.1",
+    "node-fetch": "^3.3.2"
+  },
+  "devDependencies": {
+    "@types/formidable": "^3.4.5",
+    "@types/node": "^20"
+  },
+  "peerDependencies": {},
+  "scripts": {
+    "build": "echo 'Server utils uses source files directly'",
+    "lint": "eslint . --ext .ts,.tsx"
+  }
+}

package/src/api-client.ts

@@ -0,0 +1,132 @@
+import { context, trace } from '@opentelemetry/api';
+import axios, {
+  type AxiosHeaderValue,
+  type AxiosInstance,
+  type AxiosRequestConfig,
+  type Method,
+} from 'axios';
+
+/**
+ * Configuration for creating a backend API client
+ */
+export interface ApiClientConfig {
+  /** Function to get WAF bypass token */
+  getWafBypassToken?: () => string | undefined;
+  /** Optional base URL for API requests */
+  baseURL?: string;
+  /** Enable tracing headers */
+  enableTracing?: boolean;
+}
+
+/**
+ * Creates a configured axios instance with automatic header injection
+ * Automatically adds:
+ * - Authorization header (Bearer token)
+ * - WAF bypass header (X-RXB-Bypass)
+ * - Tracing headers (traceparent)
+ * - Application header
+ */
+export function createBackendApiClient(config: ApiClientConfig = {}): {
+  request: <T = unknown>(options: AxiosRequestConfig & { accessToken: string }) => Promise<T>;
+  getInstance: () => AxiosInstance;
+} {
+  const { getWafBypassToken, baseURL, enableTracing = true } = config;
+
+  const instance = axios.create({
+    baseURL,
+    timeout: 30000,
+  });
+
+  // Add request interceptor to inject headers
+  instance.interceptors.request.use((requestConfig) => {
+    const headers = requestConfig.headers || {};
+
+    // Get tracing context if enabled
+    if (enableTracing) {
+      const span = trace.getSpan(context.active());
+      const traceContext = span?.spanContext();
+      if (traceContext) {
+        headers['traceparent'] = `00-${traceContext.traceId}-${traceContext.spanId}-01`;
+      }
+    }
+
+    // Add Application header
+    headers['Application'] = 'authorization';
+
+    requestConfig.headers = headers;
+    return requestConfig;
+  });
+
+  return {
+    /**
+     * Make an API request with automatic header injection
+     * @param options Axios request config with accessToken
+     * @returns Response data
+     */
+    request: async <T = unknown>(
+      options: AxiosRequestConfig & { accessToken: string }
+    ): Promise<T> => {
+      const { accessToken, ...axiosConfig } = options;
+
+      const headers: Record<string, AxiosHeaderValue> = {
+        ...(axiosConfig.headers as Record<string, AxiosHeaderValue>),
+        Authorization: `Bearer ${accessToken}`,
+      };
+
+      // Add WAF bypass header if available
+      const wafToken = getWafBypassToken?.();
+      if (wafToken) {
+        headers['X-RXB-Bypass'] = wafToken;
+      }
+
+      const response = await instance.request<T>({
+        ...axiosConfig,
+        headers,
+      });
+
+      return response.data;
+    },
+
+    getInstance: () => instance,
+  };
+}
+
+/**
+ * Create headers for backend API requests with all required tokens
+ * Useful for fetch() or other HTTP clients
+ */
+export function createBackendHeaders(options: {
+  accessToken: string;
+  wafBypassToken?: string;
+  contentType?: string;
+  enableTracing?: boolean;
+}): Record<string, string> {
+  const {
+    accessToken,
+    wafBypassToken,
+    contentType = 'application/json',
+    enableTracing = true,
+  } = options;
+
+  const headers: Record<string, string> = {
+    'Content-Type': contentType,
+    Authorization: `Bearer ${accessToken}`,
+    Application: 'authorization',
+  };
+
+  // Add WAF bypass header if provided
+  if (wafBypassToken) {
+    headers['X-RXB-Bypass'] = wafBypassToken;
+  }
+
+  // Add tracing if enabled
+  if (enableTracing) {
+    const span = trace.getSpan(context.active());
+    const traceContext = span?.spanContext();
+    if (traceContext) {
+      headers['traceparent'] = `00-${traceContext.traceId}-${traceContext.spanId}-01`;
+    }
+  }
+
+  return headers;
+}

package/src/call-java-handler.ts

@@ -0,0 +1,369 @@
+import * as fs from 'fs';
+
+import { getLogger, getUser } from '@rxbenefits/utils/logger';
+import { ProviderSetup } from '@rxbenefits/utils/tracer';
+import { context, trace } from '@opentelemetry/api';
+import axios, { type Method } from 'axios';
+import * as formidable from 'formidable';
+import type { NextApiRequest, NextApiResponse } from 'next';
+import fetch, { Blob, FormData } from 'node-fetch';
+
+import { createBackendHeaders } from './api-client';
+
+const logger = getLogger();
+const shouldLogAuthDebug = Boolean(process.env.AWS_REGION || process.env.AUTH0_DEBUG);
+
+const getCookieNames = (cookieHeader?: string | string[]) => {
+  const raw = Array.isArray(cookieHeader) ? cookieHeader.join(';') : cookieHeader;
+  if (!raw) return [];
+  return raw
+    .split(';')
+    .map((cookie) => cookie.trim().split('=')[0])
+    .filter(Boolean);
+};
+
+const buildAuthDebugInfo = (req: NextApiRequest) => {
+  const cookieNames = getCookieNames(req.headers.cookie);
+  const hasDefaultSession = cookieNames.some(
+    (name) => name === 'appSession' || name.startsWith('appSession.')
+  );
+
+  return {
+    method: req.method,
+    url: req.url,
+    host: req.headers.host,
+    forwardedHost: req.headers['x-forwarded-host'],
+    forwardedProto: req.headers['x-forwarded-proto'],
+    referer: req.headers.referer,
+    cookieCount: cookieNames.length,
+    cookieNames,
+    hasAdminPortalSession: cookieNames.includes('admin_portal_session'),
+    hasAdminPortalTransaction: cookieNames.includes('admin_portal_auth_verification'),
+    hasDefaultSession,
+  };
+};
+
+const buildUpstreamDebugInfo = (params: {
+  route: string;
+  targetUrl: string;
+  method: Method;
+  sendType: string;
+  error: unknown;
+  status?: number;
+}) => {
+  const error = params.error as { name?: string; code?: string; message?: string } | undefined;
+  return {
+    route: params.route,
+    targetUrl: params.targetUrl,
+    method: params.method,
+    sendType: params.sendType,
+    status: params.status,
+    errorName: error?.name,
+    errorCode: error?.code,
+    errorMessage: error?.message,
+  };
+};
+
+/**
+ * Service configuration for callJava handler
+ * Can be a static object or a function that returns config (for lazy evaluation)
+ * 
+ * AI-Modified: Added function support for lazy evaluation of env vars
+ * In Lambda/SSR, module-level code runs before loadAuth0Config() populates process.env
+ * Modified-Date: 2026-01-21
+ */
+export type ServiceConfig = Record<string, string> | (() => Record<string, string>);
+
+/**
+ * Request body shape for callJava endpoint
+ */
+export type CallJavaRequestBody = {
+  sendType?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'blob';
+  method: Method;
+  data?: Record<string, any>;
+  route: string;
+};
+
+/**
+ * Configuration for auth functions
+ */
+export interface CallJavaAuthConfig {
+  getAccessToken: (req: NextApiRequest, res: NextApiResponse) => Promise<{ accessToken?: string }>;
+  withApiAuthRequired: (handler: any) => any;
+  getWafBypassToken: () => string | undefined;
+}
+
+/**
+ * Creates a Next.js API route handler for the callJava pattern
+ * Handles proxying requests to backend services with automatic header injection
+ *
+ * @param services Service key -> base URL mapping
+ * @param auth Auth0 functions for authentication and WAF bypass
+ * @returns Next.js API route handler
+ *
+ * @example
+ * ```ts
+ * import { createCallJavaHandler } from '@rxbenefits/server-utils';
+ * import { getAccessToken, withApiAuthRequired, getWafBypassToken } from '../../lib/auth0';
+ *
+ * const services = {
+ *   'fms-commission-service': process.env.FMSCOMMISSIONAPIURI || '',
+ *   'ben-admin': process.env.BENADMINAPIURI || '',
+ * };
+ *
+ * export const config = { api: { bodyParser: false } };
+ * export default createCallJavaHandler(services, {
+ *   getAccessToken,
+ *   withApiAuthRequired,
+ *   getWafBypassToken,
+ * });
+ * ```
+ */
+export function createCallJavaHandler(services: ServiceConfig, auth: CallJavaAuthConfig) {
+  return auth.withApiAuthRequired(async function callJava(
+    req: NextApiRequest,
+    res: NextApiResponse
+  ) {
+    ProviderSetup();
+    const span = trace.getSpan(context.active());
+
+    try {
+      const { accessToken } = await auth.getAccessToken(req, res);
+
+      if (!accessToken) {
+        if (shouldLogAuthDebug) {
+          logger.error('[AuthDebug] /api/callJava missing access token', buildAuthDebugInfo(req));
+        }
+        logger.error('no access token');
+        res.status(401).end(JSON.stringify({ message: 'no access token' }));
+        return;
+      }
+
+      const username = getUser(accessToken);
+      span?.setAttribute('app.user', username);
+
+      const reqData: any = await getFormData(req);
+      const formattedData = formatData(reqData);
+      span?.setAttribute('http.target_route', formattedData.fields.route);
+      span?.setAttribute('http.target_method', formattedData.fields.method);
+
+      // legacy shape: move `data` to `body`
+      formattedData.fields.body = formattedData.fields.data;
+      delete formattedData.data;
+
+      // AI-Modified: Resolve services if it's a function (lazy evaluation for Lambda)
+      const resolvedServices = typeof services === 'function' ? services() : services;
+      
+      // Debug logging for Lambda environment
+      if (shouldLogAuthDebug) {
+        const route = formattedData.fields?.route || '';
+        const serviceKey = Object.keys(resolvedServices).find(key => route.includes(key));
+        const serviceUrl = serviceKey ? resolvedServices[serviceKey] : 'unknown';
+        logger.info('[CallJava] Service resolution', {
+          route,
+          serviceKey: serviceKey || 'none',
+          serviceUrl: serviceUrl ? `${serviceUrl.substring(0, 50)}...` : 'EMPTY',
+          hasEnvVars: {
+            TASKSERVICEAPIURI: !!process.env.TASKSERVICEAPIURI,
+            ELIGIBILITYIMPORTAPIURI: !!process.env.ELIGIBILITYIMPORTAPIURI,
+          }
+        });
+      }
+
+      const response: any = await axiosRequest(
+        accessToken,
+        auth.getWafBypassToken(),
+        formattedData,
+        resolvedServices
+      );
+
+      if (response?.headers?.['content-disposition']) {
+        res.setHeader('content-disposition', response.headers['content-disposition']);
+      }
+
+      // If axios response, send only the upstream payload
+      if (response && typeof response === 'object' && 'data' in response) {
+        res.send((response as { data: unknown }).data);
+      } else if (
+        response &&
+        typeof response === 'object' &&
+        typeof (response as any).pipe === 'function'
+      ) {
+        // node-fetch stream body (multipart)
+        (response as any).pipe(res);
+      } else {
+        res.status(500).send({ message: 'Upstream request failed' });
+      }
+      span?.end();
+    } catch (error: any) {
+      if (shouldLogAuthDebug) {
+        logger.error('[AuthDebug] /api/callJava error', {
+          error: error instanceof Error ? error.message : String(error),
+          ...buildAuthDebugInfo(req),
+        });
+      }
+      logger.error(error);
+      const status: number = error?.response?.status || 500;
+      // Avoid leaking upstream error details to the client
+      res.status(status).send({ message: 'Request failed' });
+      span?.end();
+    }
+  });
+}
+
+const formatData = (data: any) => {
+  if (typeof data.fields.method === 'string') return data;
+  const newData = data;
+  const formattedData: Record<string, string> = {};
+  const keys = Object.keys(newData.fields);
+  for (let i = 0; i < keys.length; i++) {
+    const val = newData.fields[keys[i]][0];
+    formattedData[keys[i]] = val;
+  }
+  newData.fields = formattedData;
+  return newData;
+};
+
+const getFormData = async (req: any) => {
+  const data = await new Promise((resolve, reject) => {
+    const form = new formidable.Formidable();
+
+    form.parse(req, (err, fields, files) => {
+      if (err) reject({ err });
+      resolve({ err, fields, files });
+    });
+  });
+  return data;
+};
+
+const findService = (url: string, services: Record<string, string>) => {
+  let newUrl = url;
+  const keys = Object.keys(services);
+
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const replacement = services[key];
+    if (replacement && newUrl.includes(key)) {
+      newUrl = newUrl.replace(key, replacement);
+      break;
+    }
+  }
+  return newUrl;
+};
+
+const axiosRequest = async (
+  accessToken: string,
+  wafBypassToken: string | undefined,
+  requestData: any,
+  services: Record<string, string>
+) => {
+  const {
+    route: url,
+    method = 'GET',
+    body,
+    sendType = 'application/json',
+    ...rest
+  } = requestData.fields;
+
+  let sendBody = body;
+
+  // Create headers with WAF bypass token
+  const headers = createBackendHeaders({
+    accessToken,
+    wafBypassToken,
+    contentType: sendType,
+    enableTracing: true,
+  });
+
+  if (sendType === 'blob') {
+    (headers as any).responseType = 'arraybuffer';
+  }
+
+  if (sendType === 'multipart/form-data') {
+    sendBody = { ...rest };
+    const form = new FormData();
+    const keys = Object.keys(sendBody);
+    const fileKeys = Object.keys(requestData.files || {});
+
+    for (let i = 0; i < keys.length; i++) {
+      form.append(keys[i], sendBody[keys[i]]);
+    }
+
+    if (fileKeys.length) {
+      for (let i = 0; i < fileKeys.length; i++) {
+        const file = requestData.files[fileKeys[i]]?.[0];
+        if (!file?.filepath) continue;
+        const buffer = fs.readFileSync(file.filepath);
+        const blob = new Blob([new Uint8Array(buffer)]);
+        form.append(fileKeys[i], blob, file?.originalFilename);
+      }
+    }
+
+    const targetUrl: string = findService(url, services) || '';
+    try {
+      const response = await fetch(targetUrl, {
+        method,
+        body: form,
+        headers,
+      });
+
+      if (!response.ok && shouldLogAuthDebug) {
+        logger.error(
+          buildUpstreamDebugInfo({
+            route: url,
+            targetUrl,
+            method,
+            sendType,
+            status: response.status,
+            error: new Error(response.statusText),
+          }),
+          '[ApiDebug] /api/callJava upstream fetch response'
+        );
+      }
+
+      // For uploads/downloads, return the raw stream body
+      return response.body;
+    } catch (error) {
+      if (shouldLogAuthDebug) {
+        logger.error(
+          buildUpstreamDebugInfo({
+            route: url,
+            targetUrl,
+            method,
+            sendType,
+            error,
+          }),
+          '[ApiDebug] /api/callJava upstream fetch failed'
+        );
+      }
+      throw error;
+    }
+  }
+
+  const targetUrl: string = findService(url, services) || '';
+
+  try {
+    return await axios.request({
+      url: targetUrl,
+      method,
+      data: sendBody,
+      headers,
+      responseType: (headers as any).responseType,
+    });
+  } catch (error) {
+    if (shouldLogAuthDebug) {
+      logger.error(
+        buildUpstreamDebugInfo({
+          route: url,
+          targetUrl,
+          method,
+          sendType,
+          status: (error as any)?.response?.status,
+          error,
+        }),
+        '[ApiDebug] /api/callJava upstream request failed'
+      );
+    }
+    throw error;
+  }
+};

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @rxbenefits/server-utils
+ *
+ * Shared server-side utilities for Next.js API routes
+ * Provides centralized handling of:
+ * - WAF bypass headers
+ * - Authentication headers
+ * - Tracing headers
+ * - Backend API proxying
+ */
+
+export * from './api-client';
+export * from './call-java-handler';

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": ".."
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}