@benup/bensdk 1.11.12 → 1.11.14

package/bin/lib/types/benefit-definition.types.d.ts

@@ -2,11 +2,13 @@ import z from 'zod';
 import { EmploymentContracts } from '@benup-dev/benup-api';
 import { AxiosInstance } from 'axios';
 import { BenefitDefinitionSchema } from '../schemas/benefit-definition.schema';
+import { LockHelper } from './lib/lock-helper.lib.type';
 import { TokenHelper } from './lib/token-helper.lib.type';
 import { StateHandlerCtx, WebhookRequest, WebhookResponse } from './state-handler.types';
 type Base = z.infer<typeof BenefitDefinitionSchema>;
 export type AuthHandlerCtx = {
     tokenHelper: TokenHelper;
+    lockHelper: LockHelper;
     employmentContract: z.infer<typeof EmploymentContracts.default.collection.default>;
 };
 export type AuthHandlerResult = {
@@ -17,7 +19,28 @@ export type AuthHandlerResult = {
     outcome: 'SUCCEEDED';
     instance?: AxiosInstance;
 };
+export type CredentialsHealthCheckResult = {
+    outcome: 'FAILED';
+    reason?: string;
+} | {
+    outcome: 'SUCCEEDED';
+} | {
+    outcome: 'RETRY';
+    reason?: string;
+};
 export type BenefitDefinition = Omit<Base, 'stateMachine'> & {
+    /**
+     * Defines if the benefit integrates via file-exchange
+     * if so it should define which engine-type use via type
+     * which mime-type of file generated a csv? so 'text/csv'
+     * and template field defines other name for template used file, the default is
+     * looking for #shared/definitions/benefitID/template.handlebars so it will become -> #shared/definitions/benefitID/{{template}}
+     */
+    fileIntegration?: {
+        type: 'handlebars';
+        mime: 'text/csv' | 'text/plain';
+        template?: string;
+    };
     stateMachine: Base['stateMachine'] & {
         DEDUCTION_FILE_INGESTION?: {
             REQUESTED_DEDUCTION_FILE_INGESTION: {
@@ -35,6 +58,7 @@ export type BenefitDefinition = Omit<Base, 'stateMachine'> & {
     };
     auth?: {
         handler: (credentials: any, ctx: any) => Promise<AuthHandlerResult>;
+        credentialsHealthCheckHandler?: (credentials: any) => Promise<CredentialsHealthCheckResult>;
     };
 };
 export {};

package/bin/lib/types/lib/lock-helper.lib.type.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Type definition for distributed lock helper
+ *
+ * Problem: Multiple action-consumer instances process messages in "parallel" and call
+ * auth handlers concurrently. When tokens are not cached, this causes simultaneous
+ * API calls to vendor's auth endpoint, resulting in:
+ * - Rate limiting issues
+ * - Redundant credential exchanges
+ * - Potential auth failures
+ *
+ * Solution: Use a distributed lock (Redis-based) to ensure only one instance authenticates
+ * at a time. This is a "partial" solution that fails open gracefully: if Redis is unavailable,
+ * locks cannot be acquired and the message will be retried.
+ *
+ * Implementation: See auth-lock.ts for the Redis-based implementation
+ */
+export type LockHelper = {
+    /**
+     * Executes a function while holding a lock
+     * If lock cannot be acquired, throws an error
+     * @param key - Lock key
+     * @param fn - Function to execute
+     * @returns Result of function
+     */
+    executeWithLock: <T>(key: string, fn: () => Promise<T>) => Promise<T>;
+};

package/bin/lib/types/state-handler.types.d.ts

@@ -68,6 +68,10 @@ export interface StateHandlerCtx {
      * benefitPartnerAPI Axios instance
      */
     benefitPartnerAPI?: AxiosInstance;
+    /**
+     * dataGatewayAPI Axios instance
+     */
+    dataGatewayAPI: AxiosInstance;
     /**
      * deductionFileIngestionHelper
      */

package/package.json

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