@rxbenefits/server-utils 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+> @admin-portal/server-utils@0.0.0 build /Users/dmalone/Documents/GitHub/admin-portal/packages/server-utils
+> echo 'Server utils uses source files directly'
+
+Server utils uses source files directly

package/.turbo/turbo-lint.log

@@ -0,0 +1,5 @@
+
+> @admin-portal/server-utils@0.0.0 lint /Users/dmalone/Documents/GitHub/admin-portal/packages/server-utils
+> eslint . --ext .ts,.tsx
+
+Pages directory cannot be found at /Users/dmalone/Documents/GitHub/admin-portal/packages/server-utils/pages or /Users/dmalone/Documents/GitHub/admin-portal/packages/server-utils/src/pages. If using a custom path, please configure with the `no-html-link-for-pages` rule in your eslint config file.

package/README.md

@@ -0,0 +1,384 @@
+# @rxbenefits/server-utils
+
+Shared server-side utilities for Next.js API routes across all microfrontends.
+
+## Purpose
+
+This package centralizes common server-side API functionality to:
+
+- **Automatically inject WAF bypass headers** on all backend API requests
+- **Eliminate code duplication** across shell, ben-admin, financials, and future microfrontends
+- **Ensure consistency** in how we handle authentication, tracing, and backend communication
+- **Simplify migration** of new microfrontends by providing pre-built API handlers
+
+## Quick Start
+
+Choose the implementation pattern that matches your app architecture:
+
+- **Pages Router (shell, financials)**: Use [`createCallJavaHandler()`](#pattern-1-pages-router-calljava-handler) for `/pages/api/` routes
+- **App Router (ben-admin)**: Use [`createBackendHeaders()`](#pattern-2-app-router-backend-headers) for `/app/api/` routes
+
+---
+
+## Implementation Patterns
+
+### Pattern 1: Pages Router - CallJava Handler
+
+**When to use**: Pages Router apps (shell, financials) that need to proxy requests to backend Java services.
+
+**File**: `apps/{your-app}/pages/api/callJava.ts`
+
+#### Step 1: Add Dependency
+
+Ensure `@rxbenefits/server-utils` is in your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@rxbenefits/server-utils": "workspace:*"
+  }
+}
+```
+
+#### Step 2: Create callJava Route
+
+```typescript
+//************************DO NOT EDIT WITHOUT NOTIFYING Sam or Ken  **********************************
+import { createCallJavaHandler } from '@rxbenefits/server-utils';
+
+import { getAccessToken, withApiAuthRequired, getWafBypassToken } from '../../lib/auth0';
+
+/**
+ * Service key -> base URL mapping
+ * The incoming `route` field may contain one of these keys, which will be replaced with the configured URL.
+ */
+const services = {
+  'fms-commission-service': process.env.FMSCOMMISSIONAPIURI || '',
+  'fms-invoicing-service': process.env.FMSINVOICEAPIURI || '',
+  'eligibility-imports-service': process.env.ELIGIBILITYIMPORTAPIURI || '',
+  'audit-service': process.env.AUDITAPIURI || '',
+  'billing-service': process.env.FMSBILLINGSERVICEURI || '',
+  'bms-service': process.env.BMSAPIURI || '',
+  'task-service': process.env.TASKSERVICEAPIURI || '',
+  'ben-admin': process.env.BENADMINAPIURI || 'https://ben-admin.dev.rxbenefits.cloud/v1',
+  'com-manager-service':
+    process.env.COMMANAGERSERVICEURI || 'https://communication-manager-service-qa.rxbenefits.cloud',
+} as const;
+
+export const config = {
+  api: {
+    bodyParser: false,
+  },
+};
+
+/**
+ * CallJava API route handler
+ * Uses centralized handler from @rxbenefits/server-utils with automatic:
+ * - WAF bypass header injection
+ * - Authentication header injection
+ * - Tracing header injection
+ * - Error handling
+ */
+export default createCallJavaHandler(services, {
+  getAccessToken,
+  withApiAuthRequired,
+  getWafBypassToken,
+});
+```
+
+#### Step 3: Ensure Auth0 WAF Support
+
+Make sure your `lib/auth0.ts` exports `getWafBypassToken`:
+
+```typescript
+export function getWafBypassToken(): string | undefined {
+  return auth0Config?.wafBypassToken || process.env.WAF_BYPASS_TOKEN;
+}
+```
+
+**That's it!** Your callJava route now automatically includes WAF bypass headers on all requests.
+
+**Reference Examples**:
+
+- [`apps/shell/pages/api/callJava.ts`](../../apps/shell/pages/api/callJava.ts)
+- [`apps/financials/pages/api/callJava.ts`](../../apps/financials/pages/api/callJava.ts)
+
+---
+
+### Pattern 2: App Router - Backend Headers
+
+**When to use**: App Router apps (ben-admin) with custom API handlers that need WAF headers.
+
+**Files**:
+
+- `apps/{your-app}/app/api/apiHandler.ts`
+- `apps/{your-app}/app/api/graphql/route.ts`
+- Any custom App Router API routes
+
+#### Step 1: Add Dependency
+
+Ensure `@rxbenefits/server-utils` is in your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@rxbenefits/server-utils": "workspace:*"
+  }
+}
+```
+
+#### Step 2: Update Your API Handler
+
+Import `createBackendHeaders` and replace manual header construction:
+
+**Before**:
+
+```typescript
+const headers: Record<string, string> = {
+  'Content-Type': contentType ?? 'application/json',
+  Authorization: `Bearer ${accessToken}`,
+  Application: 'authorization',
+};
+```
+
+**After**:
+
+```typescript
+import { createBackendHeaders } from '@rxbenefits/server-utils';
+import { getWafBypassToken } from '@/lib/auth0';
+
+const headers: Record<string, string> = createBackendHeaders({
+  accessToken: accessToken || '',
+  wafBypassToken: getWafBypassToken(),
+  contentType: contentType ?? 'application/json',
+  enableTracing: false, // Set true if you want OpenTelemetry tracing
+});
+```
+
+#### Step 3: Example - apiHandler.ts
+
+```typescript
+import { createBackendHeaders } from '@rxbenefits/server-utils';
+import { NextRequest, NextResponse } from 'next/server';
+
+import { apiConfig } from './apiMaps';
+import type { ApiParams } from './apiMapsHelper';
+
+import { getAccessToken, withApiAuthRequired, getWafBypassToken } from '@/lib/auth0';
+
+const fetchData = async (
+  key: string,
+  method: string,
+  req: NextRequest,
+  params: ApiParams | undefined
+): Promise<unknown> => {
+  const res = new NextResponse();
+  const { accessToken } = await getAccessToken(req, res);
+
+  const urlConfig = apiConfig[key];
+  let url = typeof urlConfig.url === 'function' ? await urlConfig.url(params) : urlConfig.url;
+
+  // Use centralized header builder with automatic WAF bypass, auth, and tracing
+  const headers: Record<string, string> = createBackendHeaders({
+    accessToken: accessToken || '',
+    wafBypassToken: getWafBypassToken(),
+    contentType: req.headers.get('content-type') ?? 'application/json',
+    enableTracing: false,
+  });
+
+  const response = await fetch(url, {
+    method,
+    headers,
+    body: method !== 'GET' ? await req.text() : undefined,
+  });
+
+  return response.json();
+};
+```
+
+#### Step 4: Example - GraphQL Route
+
+```typescript
+import { createBackendHeaders } from '@rxbenefits/server-utils';
+
+import { getAccessToken, withApiAuthRequired, getWafBypassToken } from '@/lib/auth0';
+import { NextRequest, NextResponse } from 'next/server';
+
+export const POST = withApiAuthRequired(async (request: NextRequest) => {
+  try {
+    const res = new NextResponse();
+    const { accessToken } = await getAccessToken(request, res);
+
+    if (!accessToken) {
+      return NextResponse.json({ error: 'No access token available' }, { status: 401 });
+    }
+
+    const body = await request.json();
+    const graphqlEndpoint = process.env.NEXT_PUBLIC_GRAPHQL_URL;
+
+    // Use centralized header builder with automatic WAF bypass, auth, and tracing
+    const headers = {
+      ...createBackendHeaders({
+        accessToken,
+        wafBypassToken: getWafBypassToken(),
+        contentType: 'application/json',
+        enableTracing: false,
+      }),
+      Accept: 'application/json',
+    };
+
+    const response = await fetch(graphqlEndpoint, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    });
+
+    const data = await response.json();
+    return NextResponse.json(data);
+  } catch (error) {
+    console.error('GraphQL API route error:', error);
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
+  }
+});
+```
+
+**Reference Examples**:
+
+- [`apps/ben-admin/app/api/apiHandler.ts`](../../apps/ben-admin/app/api/apiHandler.ts)
+- [`apps/ben-admin/app/api/graphql/route.ts`](../../apps/ben-admin/app/api/graphql/route.ts)
+
+---
+
+## API Reference
+
+### `createBackendHeaders(options)`
+
+Creates a headers object with automatic injection of authentication, WAF, and tracing headers.
+
+**Parameters**:
+
+```typescript
+{
+  accessToken: string;        // Auth0 access token
+  wafBypassToken?: string;    // WAF bypass token (optional)
+  contentType?: string;       // Content-Type header (default: 'application/json')
+  enableTracing?: boolean;    // Enable OpenTelemetry tracing (default: false)
+}
+```
+
+**Returns**: `Record<string, string>` - Headers object ready for fetch/axios
+
+**Example**:
+
+```typescript
+const headers = createBackendHeaders({
+  accessToken: token,
+  wafBypassToken: getWafBypassToken(),
+  contentType: 'application/json',
+  enableTracing: true,
+});
+
+await fetch(url, { headers });
+```
+
+---
+
+### `createCallJavaHandler(services, auth)`
+
+Factory function that creates a complete Pages Router API handler for proxying to backend services.
+
+**Parameters**:
+
+```typescript
+services: Record<string, string>; // Service name -> base URL mapping
+auth: {
+  getAccessToken: (req, res) => Promise<{ accessToken?: string }>;
+  withApiAuthRequired: (handler: any) => any;
+  getWafBypassToken: () => string | undefined;
+}
+```
+
+**Returns**: Next.js API route handler
+
+**Example**:
+
+```typescript
+const services = {
+  'fms-commission-service': process.env.FMSCOMMISSIONAPIURI || '',
+  'ben-admin': process.env.BENADMINAPIURI || '',
+};
+
+export default createCallJavaHandler(services, {
+  getAccessToken,
+  withApiAuthRequired,
+  getWafBypassToken,
+});
+```
+
+---
+
+### `createBackendApiClient(config)`
+
+Creates an Axios instance with automatic header injection (advanced use).
+
+**Parameters**:
+
+```typescript
+{
+  getWafBypassToken?: () => string | undefined;
+  baseURL?: string;
+  enableTracing?: boolean;
+}
+```
+
+**Returns**: `{ request, getInstance }`
+
+**Note**: Most apps should use `createBackendHeaders()` or `createCallJavaHandler()` instead.
+
+---
+
+## Debugging Upstream Failures
+
+When proxy requests fail upstream, the handlers emit structured logs:
+
+- `/api/call` (shell) logs `[ApiDebug]` when `API_DEBUG=1` locally or automatically in AWS.
+- `/api/callJava` logs `[ApiDebug]` when `AUTH0_DEBUG=1` locally or automatically in AWS.
+
+These logs include the target URL, method, and error code (e.g., `ETIMEDOUT`) to help
+identify network/VPC/DNS issues. Upstream network failures return a 502 response.
+
+## Benefits
+
+### Before (Duplicated Code)
+
+Each app had its own nearly-identical `callJava.ts` with 200+ lines of code. Any bug fix or feature (like WAF headers) required updating 3+ files.
+
+### After (Centralized)
+
+Each app has a 15-line file that imports the shared handler. Bug fixes and features are applied once in this package.
+
+### Migration Impact
+
+New microfrontends can use these utilities out-of-the-box without implementing:
+
+- WAF bypass header logic
+- Tracing header logic
+- Request/response formatting
+- Error handling patterns
+
+## What Gets Automatically Added
+
+All utilities in this package automatically add:
+
+1. **Authorization Header**: `Authorization: Bearer <token>`
+2. **WAF Bypass Header**: `X-RXB-Bypass: <token>` (if available)
+3. **Application Header**: `Application: authorization`
+4. **Tracing Header**: `traceparent: <trace-context>` (if tracing enabled)
+
+## Development
+
+This package uses source files directly (no build step required):
+
+```bash
+pnpm --filter @rxbenefits/server-utils lint
+```