@benup/bensdk 1.11.16 → 1.12.0

package/bin/src/cli/templates/bensdk-local-server/app.ts

@@ -1,80 +1,278 @@
+// @ts-nocheck
 import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
 import pino from 'pino';
 import { PassThrough } from 'stream';
-import { WebSocketServer } from 'ws';
+import { WebSocket, WebSocketServer } from 'ws';
 import benefitsDefinition from '../../src/benefit-definition';
 
+// Disable TLS certificate validation in non-production environments
+// (e.g. self-signed certs used in zero-trust networks)
+if (process.env['NODE_ENV'] !== 'production') {
+  process.env['NODE_TLS_REJECT_UNAUTHORIZED'] = '0';
+}
+
+// logStream is used to forward raw pino JSON logs to WebSocket connections (viewer)
 const logStream = new PassThrough();
-const logger = pino(logStream);
+
+const logger = pino(
+  {
+    level: 'info',
+    transport: {
+      target: 'pino-pretty',
+      options: { colorize: true }
+    }
+  }
+);
+
 const app = new Hono();
 const connections = new Set<WebSocket>();
-const onLog = (chunk: Buffer) => {
+
+// Forward raw log data to WebSocket connections (used by the viewer)
+logStream.on('data', (chunk: Buffer) => {
   connections.forEach((ws) => {
     if (ws.readyState === WebSocket.OPEN) {
       ws.send(chunk.toString());
     }
   });
-};
-
-logStream.on('data', onLog);
+});
 
 app.use(cors());
 
-app.get('/state-machine', async (c) => {
-  const response = benefitsDefinition.stateMachine;
+/**
+ * dev-test.json structure:
+ * {
+ *   "credentials": { ...your real credentials here },
+ *   "eligibilityOptions": {
+ *     "GRANT": { ...options },
+ *     "RECHARGE": { ...options },
+ *     "GRANT_DEPENDENT": { ...options }
+ *   }
+ * }
+ *
+ * Copy dev-test.example.json to dev-test.json and fill in your real values.
+ * dev-test.json is gitignored — never commit real credentials.
+ */
+const devTestPath = join(process.cwd(), 'dev-test.json');
+let devTestConfig: { credentials?: Record<string, unknown>; eligibilityOptions?: Record<string, unknown> } = {};
 
-  return c.json(response, 200);
+if (existsSync(devTestPath)) {
+  devTestConfig = JSON.parse(readFileSync(devTestPath, 'utf-8'));
+  logger.info('[benSDK] Loaded dev-test.json');
+} else {
+  logger.warn('[benSDK] dev-test.json not found — create it from dev-test.example.json to enable real credentials and eligibilityOptions presets');
+}
+
+// Persistent in-memory token cache (survives between requests within the same server session)
+const tokenCache = new Map<string, string>();
+const tokenHelper = {
+  get: async ({ accountID, companyID, benefitID }: { accountID: string; companyID: string; benefitID: string }) => {
+    const key = `${accountID}:${companyID}:${benefitID}`;
+    return tokenCache.get(key) ?? null;
+  },
+  set: async ({
+    accountID,
+    companyID,
+    benefitID,
+    valueToBeStored
+  }: {
+    accountID: string;
+    companyID: string;
+    benefitID: string;
+    valueToBeStored: string;
+    storeForSeconds?: number;
+  }) => {
+    const key = `${accountID}:${companyID}:${benefitID}`;
+    tokenCache.set(key, valueToBeStored);
+  }
+};
+
+app.get('/state-machine', async (c) => {
+  return c.json(benefitsDefinition.stateMachine, 200);
 });
 
-app.post('/run-action', async (c) => {
-  const payload = await c.req.json();
-  const { run, requestPayload, message, currentContext } = payload;
+/**
+ * Find which action type (GRANT, REVOKE, RECHARGE, etc.) a handler state belongs to
+ * by looking up the state key in the stateMachine definition.
+ */
+function getActionTypeForHandler(handlerName: string): string | null {
+  const stateKey = handlerName.replace(/-/g, '_').toUpperCase();
+  for (const [action, states] of Object.entries(benefitsDefinition.stateMachine)) {
+    if (stateKey in (states as Record<string, unknown>)) {
+      return action;
+    }
+  }
+  return null;
+}
+
+const runAction = async (c) => {
+  let body: Record<string, unknown>;
+  try {
+    body = await c.req.json();
+  } catch {
+    return c.json({ error: 'Invalid JSON body' }, 400);
+  }
+
+  // Support both simplified format (payload, ctx) and legacy format (requestPayload, currentContext)
+  const run = body.run as string | undefined;
+  const requestPayload = (body.requestPayload ?? body.payload) as Record<string, unknown> | undefined;
+  const message = body.message ?? {};
+  const currentContext = (body.currentContext ?? body.ctx ?? {}) as Record<string, unknown>;
+
+  // Validate ctx against the schema defined in benefit-definition.ts
+  if (benefitsDefinition.actions?.ctx) {
+    const ctxValidation = benefitsDefinition.actions.ctx.safeParse(currentContext);
+    if (!ctxValidation.success) {
+      logger.warn(
+        `[benSDK] ctx failed schema validation: ${JSON.stringify(ctxValidation.error.format())}`
+      );
+    }
+  }
+
+  if (!run) {
+    return c.json(
+      { error: 'Missing required field: "run" (handler state name, e.g. "SYNC_EXISTING_GRANT")' },
+      400
+    );
+  }
+
+  // Dynamically import the handler file
   const fileName = `${run.toLowerCase()}.handler.ts`;
   const fileDir = `../../src/handlers/${fileName}`;
-  const handler = await import(fileDir);
+  let handler: { default: (...args: unknown[]) => Promise<unknown> };
+  try {
+    handler = await import(fileDir);
+  } catch {
+    return c.json(
+      { error: `Handler not found: ${fileName}`, hint: 'Make sure the file exists in src/handlers/' },
+      404
+    );
+  }
+
+  // Authenticate with real credentials if auth is defined and credentials are available in dev-test.json
+  let authInstance;
+  if (benefitsDefinition.auth && devTestConfig.credentials) {
+    logger.info('[benSDK] Authenticating with credentials from dev-test.json...');
+    const authResult = await benefitsDefinition.auth.handler(devTestConfig.credentials, {
+      tokenHelper,
+      logger
+    });
 
-  const { ctxMock } = (await import('../../context.config')).createStateHandlerCtxMock(
+    if (authResult.outcome === 'FAILED') {
+      logger.error(`[benSDK] Authentication failed: ${authResult.reason}`);
+      return c.json({ error: 'Authentication failed', reason: authResult.reason }, 401);
+    }
+
+    authInstance = authResult.instance;
+    logger.info('[benSDK] Authentication succeeded');
+  }
+
+  // Create context mock (disableMocks=true when we have a real authenticated instance)
+  const { ctxMock, apisMocks } = (await import('../../context.config')).createStateHandlerCtxMock(
     benefitsDefinition,
-    logger
+    logger,
+    !!authInstance
   );
 
-  logger.info(`Running: ${fileDir} to ${requestPayload.target.employee.name}`);
-  logger.info(`Current context: ${JSON.stringify(currentContext)}`);
-  logger.info(`Request Payload: ${JSON.stringify(requestPayload)}`);
+  // Inject the real authenticated axios instance into benefitPartnerAPI
+  if (authInstance) {
+    ctxMock.benefitPartnerAPI = authInstance;
+    // Apply any additional mocks from context.config to the authenticated instance
+    // (e.g. presigned URL mocks, specific endpoint stubs that don't need real calls)
+    if (apisMocks.benefitPartnerAPI && typeof apisMocks.benefitPartnerAPI === 'function') {
+      apisMocks.benefitPartnerAPI(authInstance);
+    }
+  }
+
+  // Determine which action type this handler belongs to (for eligibilityOptions lookup)
+  const actionType = getActionTypeForHandler(run);
+
+  // dev-test.json eligibilityOptions serve as defaults; request body overrides them
+  const devEligibilityOptions =
+    actionType && devTestConfig.eligibilityOptions?.[actionType]
+      ? devTestConfig.eligibilityOptions[actionType]
+      : {};
 
-  const response = await handler.default(
-    message,
-    {
-      ...requestPayload,
-      ctx: currentContext
+  // Validate dev-test.json eligibilityOptions against the schema defined in benefit-definition.ts
+  if (actionType && devTestConfig.eligibilityOptions?.[actionType]) {
+    const schema = benefitsDefinition.actions?.eligibilityOptions?.[actionType];
+    if (schema) {
+      const validation = schema.safeParse(devTestConfig.eligibilityOptions[actionType]);
+      if (!validation.success) {
+        logger.warn(
+          `[benSDK] dev-test.json eligibilityOptions.${actionType} failed schema validation: ${JSON.stringify(validation.error.format())}`
+        );
+      }
+    }
+  }
+
+  const mergedPayload = {
+    ...requestPayload,
+    eligibilityOptions: {
+      ...devEligibilityOptions,
+      ...(requestPayload?.eligibilityOptions ?? {})
     },
-    ctxMock
-  );
-  return c.json(response, 200);
-});
+    ctx: currentContext
+  };
+
+  logger.info(`[benSDK] Running handler: ${run}`);
+
+  try {
+    const response = await handler.default(message, mergedPayload, ctxMock);
+    logger.info(`[benSDK] Handler completed: ${run}`);
+    return c.json(response, 200);
+  } catch (error) {
+    logger.error(`[benSDK] Handler threw an exception: ${error?.message}`);
+    return c.json(
+      { error: 'Handler threw an exception', message: error?.message, stack: error?.stack },
+      500
+    );
+  }
+};
+
+// Simplified endpoint: POST /
+app.post('/', runAction);
+// Legacy endpoint for backward compatibility: POST /run-action
+app.post('/run-action', runAction);
 
 const wss = new WebSocketServer({ noServer: true });
 wss.on('connection', (ws) => {
   connections.add(ws);
 
   ws.on('message', (message) => {
-    console.log('Message received:', message.toString());
+    logger.debug(`WebSocket message: ${message.toString()}`);
   });
 
   ws.on('close', () => {
-    console.log('Close connection');
     connections.delete(ws);
   });
 });
 
 async function startServer() {
-  return new Promise((res: any, rej: any) => {
-    const server = serve({ fetch: app.fetch, port: 3000 });
+  return new Promise((res: () => void) => {
+    const server = serve({ fetch: app.fetch, port: 3000 }, () => {
+      logger.info('benSDK dev server running at http://localhost:3000');
+      logger.info('  POST /              — Run a handler (e.g. { "run": "SYNC_EXISTING_GRANT", "payload": {}, "ctx": {} })');
+      logger.info('  POST /run-action    — Run a handler (legacy format)');
+      logger.info('  GET  /state-machine — Get the state machine definition');
+
+      if (devTestConfig.credentials) {
+        logger.info('  ✓ Real credentials loaded — benefitPartnerAPI will use real API calls');
+      } else {
+        logger.warn('  ⚠ No credentials found — benefitPartnerAPI will use mocked responses from context.config.ts');
+      }
+
+      if (devTestConfig.eligibilityOptions) {
+        const actions = Object.keys(devTestConfig.eligibilityOptions).join(', ');
+        logger.info(`  ✓ EligibilityOptions presets loaded for: ${actions}`);
+      }
+    });
+
     server.on('upgrade', (request, socket, head) => {
-      const { url } = request;
-      if (url === '/ws') {
+      if (request.url === '/ws') {
         wss.handleUpgrade(request, socket, head, (ws) => {
           wss.emit('connection', ws, request);
         });
@@ -82,8 +280,11 @@ async function startServer() {
         socket.destroy();
       }
     });
+
     res();
   });
 }
 
+startServer();
+
 export { app, startServer };

package/bin/src/cli/templates/package.template.json

@@ -8,6 +8,8 @@
     "format": "npx prettier --write .",
     "lint": "npx tsc --noemit && npx prettier --check . && npx eslint .",
     "start": "cd bin/viewer && tsx startup.ts",
+    "dev:start": "tsx bin/server/app.ts",
+    "docs:update": "tsx bin/docs/update-readme.ts",
     "generate": "tsx bin/cli/generate.ts",
     "build": "tsc"
   },
@@ -48,6 +50,7 @@
     "svelte-check": "^4.0.0",
     "vite": "^6.2.5",
     "marked": "^15.0.10",
-    "open": "^10.1.1"
+    "open": "^10.1.1",
+    "pino-pretty": "^13.0.0"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benup/bensdk",
-  "version": "1.11.16",
+  "version": "1.12.0",
   "main": "index.js",
   "type": "module",
   "scripts": {