@benup/bensdk 1.11.16 → 1.12.0

package/bin/src/cli/templates/bensdk-base/README.md.template

@@ -1,110 +1,88 @@
-# 📦 BenSDK App - Documentação Inicial
+<img src="ICON.png" alt="BenefitID" width="120">
 
-Bem-vindo ao seu **BenSDK App**! Esta biblioteca, escrita em **TypeScript**, será executada dentro do nosso **integrador**, permitindo que seu benefício seja incluído, removido ou sincronizado com base em eventos.
+# bensdk - BenefitID
 
-> Este arquivo foi gerado automaticamente após a criação do projeto. Aqui você encontra tudo o que precisa para começar a desenvolver seu benefício.
-
-
-## 🔧 Estrutura do Projeto
+## Estrutura do Projeto
 
 ```
 ├── src/
-│   ├── handlers/                # Handlers chamados pelo integrador
-│   └── ...                      # Seu código principal vai aqui
-├── lib/                         # Types usados pelo integrador (não editar!)
-├── .benSDK                      # Token de publicação
-├── .benSDKIgnore               # Ignora arquivos na publicação
-├── benefit-definition.ts       # Definição do benefício + máquina de estados
-
+│   ├── benefit-definition.ts    # Definição do benefício + máquina de estados
+│   ├── handlers/                # Handlers executados pelo integrador
+│   └── lib/                     # Utilitários e mocks
+├── bin/
+│   ├── cli/                     # CLI para geração de handlers e testes
+│   └── server/                  # Servidor local para testes (npm run dev:start)
+├── ICON.png                     # Ícone do benefício
+├── .benSDKIgnore                # Ignora arquivos no empacotamento
+└── dev-test.example.json        # Modelo de credenciais para testes locais
 ```
 
+## Conceitos Básicos
 
-## ⚙️ Conceitos Básicos
-
-### 📤 Actions
+### Actions
 
-As **Actions** são comandos enviados pelo integrador ao seu BenApp. Cada action representa um evento (ex: inclusão de um funcionário) e será processada de acordo com a **máquina de estados** definida no arquivo `benefit-definition.ts`.
+As **Actions** são os eventos enviados pelo integrador ao seu BenSDK. Cada action representa uma operação sobre um benefício (ex: concessão, revogação, recarga) e é processada de acordo com a **máquina de estados** definida em `src/benefit-definition.ts`.
 
-### 🧠 Handlers
+### Handlers
 
-Os **handlers** são os pontos de entrada do seu app. Cada um processa uma Action específica. Você pode usar o padrão de desenvolvimento que preferir, desde que:
+Cada **estado** da máquina de estados corresponde a um arquivo de handler em `src/handlers/`. O handler recebe:
 
-- Mantenha os arquivos existentes    
-- Mantenha o `default export` de cada handler
-#### Handlers disponíveis:
+- `message`: contexto da mensagem recebida da fila
+- `action`: dados da operação (funcionário, empresa, eligibilityOptions, ctx compartilhado)
+- `ctx`: contexto de execução (APIs, logger, benefitDefinition)
 
-- `request_create_employee.handler.ts` → Quando um funcionário for incluído no benefício
-- `request_remove_employee.handler.ts` → Quando um funcionário for removido
-- `sync_existing_grant.handler.ts` → Verifica se o funcionário **já possui** o benefício
-- `sync_existing_revoke.handler.ts` → Verifica se o funcionário **já foi removido**
+### ctx: Contexto compartilhado entre handlers
 
-**Exemplo de handler:**
+O campo `ctx` dentro de `action` é um objeto de estado acumulado ao longo de um fluxo. Use-o para passar dados entre etapas, por exemplo, um ID retornado pela API do parceiro que será necessário em handlers subsequentes.
 
-```ts
-const handler: StateHandler<
-  ActionGrant,
-  ActionLogGrant['REQUEST_CREATE_EMPLOYEE'],
-  ActionCtx
-> = async (message, action, ctx) => {
-  // Aqui você chama a API do seu benefício, por exemplo.
-
-  return {
-    handlerResponse: { response: 'ACK' },
-    action: {
-      state: stateMachine.next,
-      ctx: {},
-      logs: { date: new Date().toISOString() },
-    },
-  };
-};
-
-export default handler;
-
-```
+## Fluxos
 
-### 🔁 Máquina de Estados
+### Concessão de Benefício (GRANT)
 
-A **máquina de estados** define a ordem de execução das actions. Para a maioria dos casos, o modelo padrão já é suficiente — mas ele pode ser adaptado conforme sua necessidade, desde que preserve os **estados finais**.
-
-#### ✅ Concessão de Benefício (GRANT)
-
-Nesse fluxo, o integrador:
-1. Verifica se o funcionário já está no benefício (`SYNC_EXISTING_GRANT` - Executando o handler `sync_existing_grant.handler.ts`).
-2. Caso não esteja, solicita sua inclusão (`REQUEST_CREATE_EMPLOYEE` - Executando o handler `request_create_employee.handler.ts` ).
-
-```mermaid 
+```mermaid
 flowchart TD
-  START([Start]) --> REQUESTED_GRANT
-  REQUESTED_GRANT -->|next| SYNC_EXISTING_GRANT["SYNC_EXISTING_GRANT"]
+  START([Início]) --> REQUESTED_GRANT
+  REQUESTED_GRANT -->|next| SYNC_EXISTING_GRANT
   SYNC_EXISTING_GRANT -->|next| REQUEST_CREATE_EMPLOYEE
   SYNC_EXISTING_GRANT -->|skip| GRANTED
   REQUEST_CREATE_EMPLOYEE -->|next| GRANTED
   REQUEST_CREATE_EMPLOYEE -->|fail| FAILED_TO_GRANT
 
+  GRANTED([GRANTED ✅])
+  FAILED_TO_GRANT([FAILED_TO_GRANT ❌])
 ```
 
-#### ❌ Revogação de Benefício (REVOKE)
-
-Nesse fluxo, o integrador:
-1. Verifica se o funcionário já foi removido do benefício (`SYNC_EXISTING_REVOKE`).
-2. Caso não tenha sido, solicita sua revogação (`REQUEST_REMOVE_EMPLOYEE`).
+### Revogação de Benefício (REVOKE)
 
-```mermaid 
+```mermaid
 flowchart TD
-  START([Start]) --> REQUESTED_REVOKE
-  REQUESTED_REVOKE -->|next| SYNC_EXISTING_REVOKE["SYNC_EXISTING_REVOKE"]
+  START([Início]) --> REQUESTED_REVOKE
+  REQUESTED_REVOKE -->|next| SYNC_EXISTING_REVOKE
   SYNC_EXISTING_REVOKE -->|next| REQUEST_REMOVE_EMPLOYEE
   SYNC_EXISTING_REVOKE -->|skip| REVOKED
   REQUEST_REMOVE_EMPLOYEE -->|next| REVOKED
   REQUEST_REMOVE_EMPLOYEE -->|fail| FAILED_TO_REVOKE
 
+  REVOKED([REVOKED ✅])
+  FAILED_TO_REVOKE([FAILED_TO_REVOKE ❌])
 ```
 
-## 🚀 Próximos Passos
+## Comandos
 
-1. Edite os arquivos em `src/handlers/` para integrar com sua API de benefício.
-2. Teste sua integração através do painel executando o comando `npm run start`
-3. Preencha seu token `.benSDK` para publicar quando estiver pronto.
-4. Rode o `ben deploy` dentro da pasta da sua aplicação, não se preocupe, vamos checar se tá tudo certo antes de efetivamente colocar em produção
+| Comando | Descricao |
+|---------|-----------|
+| `npm run dev:start` | Inicia o servidor local com autenticacao real contra a API do parceiro. [Ver documentacao](docs/DEV_SERVER.md) |
+| `npm run test` | Executa os testes unitarios com Vitest |
+| `npm run generate` | Gera handlers e testes a partir do `benefit-definition.ts` |
+| `npm run start` | Abre o painel visual da maquina de estados |
+| `npm run lint` | Valida tipos TypeScript, formatacao e linting |
+| `npm run build` | Compila o projeto para `dist/` |
 
-Se tiver dúvidas, consulte a documentação oficial do BenSDK ou fale com nosso time de suporte.
+## Publicação
+
+1. Instale o [maria-cli](https://github.com/benup-dev/maria) seguindo as instrucões do repositório.
+2. Execute o comando abaixo na raiz do projeto:
+
+```bash
+maria benefit deploy -r <link-ssh-do-repositorio> -n <benefitID>
+```

package/bin/src/cli/templates/bensdk-base/context.config.ts.template

@@ -1,8 +1,14 @@
-import axios from 'axios';
+import type { StateHandlerCtx } from '@benup/bensdk/bin/lib/types/state-handler.types.d.ts';
+import type { BenefitDefinition } from '@benup/bensdk/bin/lib/types/benefit-definition.types';
+import axios, { AxiosInstance } from 'axios';
 import AxiosMockAdapter from 'axios-mock-adapter';
-import { StateHandlerCtx } from './src/lib/types/state.handler.type';
+import pino, { Logger } from 'pino';
 
-export function createStateHandlerCtxMock(benefitDefinition, logger) {
+export function createStateHandlerCtxMock(
+  benefitDefinition: BenefitDefinition,
+  logger: Logger = pino(),
+  disableMocks = false
+) {
   const benupAPI = axios.create({
     validateStatus: () => true,
     baseURL: 'http://localhost/benupAPI'
@@ -18,35 +24,105 @@ export function createStateHandlerCtxMock(benefitDefinition, logger) {
     baseURL: 'http://localhost/benefitsAPI'
   });
 
+  const benefitPartnerAPI = axios.create({
+    validateStatus: () => true,
+    baseURL: 'http://localhost/benefitPartnerAPI'
+  });
+
+  // issueHelper mock: prints issues to the logger instead of sending them to a real service
+  // This way you can see issues raised by handlers during local development
+  const issuesHelper = {
+    sendIssue: async ({
+      title,
+      description,
+      fieldPath
+    }: {
+      title: string;
+      description: string;
+      fieldPath?: string;
+    }) => {
+      logger.warn(`[Issue] [${title}] ${description}${fieldPath ? ` → ${fieldPath}` : ''}`);
+    }
+  };
+
+  // When disableMocks=true the dev server will inject a real authenticated axios instance
+  // into ctxMock.benefitPartnerAPI. The mock here is a no-op passthrough function that can
+  // be applied to the authenticated instance if you need to stub specific endpoints
+  // (e.g. presigned URLs, file uploads) while keeping the rest as real API calls.
+  if (disableMocks) {
+    const apisMocks = {
+      benupAPI: new AxiosMockAdapter(benupAPI, { onNoMatch: 'throwException' }),
+      lgProxyAPI: new AxiosMockAdapter(lgProxyAPI, { onNoMatch: 'throwException' }),
+      benefitsAPI: new AxiosMockAdapter(benefitsAPI, { onNoMatch: 'throwException' }),
+
+      // Return a function so the dev server can apply mocks to the real authenticated instance.
+      // Use onNoMatch: 'passthrough' so real API calls are not blocked.
+      // Add any endpoint stubs here that you want to intercept even in real-call mode.
+      benefitPartnerAPI: (axiosInstance: AxiosInstance) => {
+        const mock = new AxiosMockAdapter(axiosInstance, { onNoMatch: 'passthrough' });
+        // Example: mock.onGet('/some-endpoint').reply(200, { ... });
+        return mock;
+      }
+    };
+
+    const ctxMock: StateHandlerCtx = {
+      rawMessage: {},
+      logger,
+      correlationIDs: {},
+      benefitsAPI,
+      lgProxyAPI,
+      benupAPI,
+      benefitDefinition,
+      benefitPartnerAPI,
+      // @ts-expect-error: universAPI intentionally omitted in mock context
+      universAPI: undefined,
+      issuesHelper
+    };
+
+    return { ctxMock, apisMocks };
+  }
+
+  // Full mock setup for unit testing (vitest). All API calls must be explicitly mocked.
   const apisMocks = {
-    benupAPI: new AxiosMockAdapter(benupAPI, {
-      onNoMatch: 'throwException'
-    }),
-    lgProxyAPI: new AxiosMockAdapter(lgProxyAPI, {
-      onNoMatch: 'throwException'
-    }),
-    benefitsAPI: new AxiosMockAdapter(benefitsAPI, {
-      onNoMatch: 'throwException'
-    })
+    benupAPI: new AxiosMockAdapter(benupAPI, { onNoMatch: 'throwException' }),
+    lgProxyAPI: new AxiosMockAdapter(lgProxyAPI, { onNoMatch: 'throwException' }),
+    benefitsAPI: new AxiosMockAdapter(benefitsAPI, { onNoMatch: 'throwException' }),
+    benefitPartnerAPI: new AxiosMockAdapter(benefitPartnerAPI, { onNoMatch: 'throwException' }),
+
+    // Reset all mock adapters between tests
+    resetMocks: function () {
+      Object.entries(this)
+        .filter(([_, value]) => value instanceof AxiosMockAdapter)
+        .forEach(([_, mockAdapter]) => {
+          (mockAdapter as AxiosMockAdapter).reset();
+        });
+    },
+
+    // Restore all mock adapters (call in afterAll to clean up)
+    restoreAll: function () {
+      Object.entries(this)
+        .filter(([_, value]) => value instanceof AxiosMockAdapter)
+        .forEach(([_, mockAdapter]) => {
+          (mockAdapter as AxiosMockAdapter).restore();
+        });
+    }
   };
 
-    // Mockar o endpoint GET /some-path para retornar 200 OK
-    apisMocks.benefitsAPI.onGet('/proxy-http/<Algum path>').replyOnce(200, {
-      values: ['123']
-    });
-  
+  // Set up your mock responses here for unit tests.
+  // Example: apisMocks.benefitPartnerAPI.onGet('/some-path').replyOnce(200, { ... });
 
   const ctxMock: StateHandlerCtx = {
     rawMessage: {},
-
     logger,
-
     correlationIDs: {},
-
     benefitsAPI,
     lgProxyAPI,
     benupAPI,
-    benefitDefinition
+    benefitDefinition,
+    benefitPartnerAPI,
+    // @ts-expect-error: universAPI intentionally omitted in mock context
+    universAPI: undefined,
+    issuesHelper
   };
 
   return { ctxMock, apisMocks };

package/bin/src/cli/templates/bensdk-base/dev-test.example.json

@@ -0,0 +1,22 @@
+{
+  "_comment": "Copy this file to dev-test.json and fill in your real values. dev-test.json is gitignored.",
+
+  "credentials": {
+    "accountID": "FILL_ME",
+    "companyID": "FILL_ME",
+    "benefitID": "FILL_ME",
+    "connection": {
+      "url": "https://api.your-partner.com"
+    },
+    "secret": {
+      "username": "FILL_ME",
+      "password": "FILL_ME"
+    }
+  },
+
+  "eligibilityOptions": {
+    "GRANT": {},
+    "RECHARGE": {},
+    "GRANT_DEPENDENT": {}
+  }
+}

package/bin/src/cli/templates/bensdk-base/docs/DEV_SERVER.md

@@ -0,0 +1,201 @@
+# Servidor de Desenvolvimento Local: `npm run dev:start`
+
+O `dev:start` sobe um servidor HTTP local (porta 3000) que permite testar qualquer handler diretamente contra a API real do parceiro, com autenticacao verdadeira e sem precisar de mocks.
+
+Isso e especialmente util porque:
+- Os dados que chegam da folha LG variam por cliente e nem sempre sao previsiveis nos testes unitarios.
+- As APIs dos parceiros tem comportamentos nao documentados que so aparecem em chamadas reais.
+- E possivel executar cada estado da maquina em sequencia, acumulando o `ctx` entre chamadas, simulando exatamente o que o integrador faria.
+
+---
+
+## Pre-requisitos
+
+Crie o arquivo `dev-test.json` na raiz do projeto a partir do modelo:
+
+```bash
+cp dev-test.example.json dev-test.json
+```
+
+Preencha com suas credenciais reais. A estrutura exata de `credentials` deve seguir o schema definido no `auth.handler` do seu `benefit-definition.ts`:
+
+```json
+{
+  "credentials": {
+    "accountID": "...",
+    "companyID": "...",
+    "benefitID": "...",
+    "connection": {
+      "url": "https://api.seu-parceiro.com"
+    },
+    "secret": {
+      "username": "...",
+      "password": "..."
+    }
+  },
+  "eligibilityOptions": {
+    "GRANT": {},
+    "RECHARGE": {}
+  }
+}
+```
+
+> **Atencao:** `dev-test.json` esta no `.gitignore` e no `.benSDKIgnore`. **Nunca commite credenciais reais.**
+
+---
+
+## Iniciando o servidor
+
+```bash
+npm run dev:start
+```
+
+Ao iniciar, o servidor exibe:
+- Se as credenciais foram carregadas com sucesso.
+- Quais acoes tem presets de `eligibilityOptions` configurados.
+- Os endpoints disponiveis.
+
+---
+
+## Endpoints
+
+### `POST /`: Executar um handler
+
+```json
+{
+  "run": "SYNC_EXISTING_GRANT",
+  "payload": {
+    "target": {
+      "employee": { "name": "...", "cpf": "...", "birthdate": "..." },
+      "company": { "cnpj": "..." }
+    },
+    "employmentContract": {
+      "benefits": {
+        "BENEFIT_ID": { "options": {} }
+      }
+    }
+  },
+  "message": {},
+  "ctx": {}
+}
+```
+
+| Campo | Tipo | Descricao |
+|-------|------|-----------|
+| `run` | `string` | Nome do estado a executar (ex: `SYNC_EXISTING_GRANT` ou `sync_existing_grant`) |
+| `payload` | `object` | Dados da action: target, employmentContract, eligibilityOptions opcionais |
+| `message` | `object` | Contexto da mensagem, pode ser `{}` em testes locais |
+| `ctx` | `object` | Contexto acumulado entre handlers (use o `ctx` retornado pelo handler anterior) |
+
+### `POST /run-action`: Formato legado
+
+Mesmo comportamento, mas utilizando os campos `requestPayload` e `currentContext` no lugar de `payload` e `ctx`.
+
+### `GET /state-machine`
+
+Retorna o objeto `stateMachine` definido em `benefit-definition.ts`.
+
+---
+
+## Como funciona por dentro
+
+```
+Requisicao POST /
+      |
+      +- Carrega credenciais do dev-test.json
+      +- Chama benefitDefinition.auth.handler(credentials, { tokenHelper, logger })
+      |   +- Token cacheado em memoria, so autentica uma vez por sessao
+      +- Injeta axios autenticado em ctx.benefitPartnerAPI
+      +- Mescla eligibilityOptions: dev-test.json < sobrescrito pelo corpo da requisicao
+      +- Valida eligibilityOptions e ctx contra os schemas do benefit-definition.ts
+      +- Executa o handler e retorna a resposta como JSON
+```
+
+---
+
+## eligibilityOptions: presets no `dev-test.json`
+
+Para nao precisar repetir as `eligibilityOptions` em cada requisicao, defina-as no `dev-test.json`. O servidor identifica automaticamente a qual action type pertence o handler informado em `run` consultando a `stateMachine`:
+
+```json
+{
+  "eligibilityOptions": {
+    "GRANT": {
+      "externalCompanyID": "12345",
+      "externalCardType": 1
+    },
+    "RECHARGE": {
+      "productCode": "VA"
+    }
+  }
+}
+```
+
+- As options do `dev-test.json` sao as **default**.
+- Se voce enviar `eligibilityOptions` no corpo da requisicao, eles **sobrescrevem** os do `dev-test.json`.
+- Erros de validacao do schema aparecem como `WARN` no terminal e nao bloqueiam a execucao.
+
+---
+
+## Testando um fluxo completo
+
+Execute os handlers na ordem da maquina de estados, acumulando o `ctx`:
+
+```bash
+# 1. Verificar se o beneficiario ja existe
+curl -s -X POST http://localhost:3000 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "run": "SYNC_EXISTING_GRANT",
+    "payload": { "target": { "employee": { ... } } },
+    "ctx": {}
+  }' | jq .
+
+# Exemplo de resposta:
+# {
+#   "handlerResponse": { "response": "ACK" },
+#   "action": {
+#     "state": "REQUEST_CREATE_EMPLOYEE",
+#     "ctx": { "someInternalID": "abc123" },
+#     "logs": { ... }
+#   }
+# }
+
+# 2. Criar o beneficiario, passando o ctx retornado acima
+curl -s -X POST http://localhost:3000 \
+  -H "Content-Type: application/json" \
+  -d '{
+    "run": "REQUEST_CREATE_EMPLOYEE",
+    "payload": { "target": { "employee": { ... } } },
+    "ctx": { "someInternalID": "abc123" }
+  }' | jq .
+```
+
+> **Dica:** Use `| jq .action.ctx` para extrair apenas o ctx da resposta e passar para o proximo handler.
+
+---
+
+## Variaveis de ambiente
+
+| Variavel | Valor | Efeito |
+|----------|-------|--------|
+| `NODE_ENV` | `production` | Mantem a validacao TLS ativa (por padrao, desabilitada em dev para suportar certificados self-signed) |
+| `VERBOSE` | `true` | Loga o payload completo de cada requisicao no terminal |
+
+---
+
+## Troubleshooting
+
+**`dev-test.json not found`**
+Crie o arquivo: `cp dev-test.example.json dev-test.json`
+
+**`Authentication failed`**
+Verifique se as credenciais em `dev-test.json` estao corretas e se a URL da API esta acessivel a partir da sua maquina.
+
+**`Handler not found: sync_existing_grant.handler.ts`**
+Verifique se:
+1. O nome em `run` corresponde a um estado da `stateMachine` em `benefit-definition.ts`.
+2. O arquivo `src/handlers/{estado}.handler.ts` existe (rode `npm run generate` para gera-lo).
+
+**TLS / certificados self-signed**
+Em ambientes com zero-trust ou proxies com certificados self-signed, o servidor ja desabilita a verificacao TLS automaticamente (exceto quando `NODE_ENV=production`).

package/bin/src/cli/templates/bensdk-docs/update-readme.ts

@@ -0,0 +1,96 @@
+// @ts-nocheck
+/**
+ * npm run docs:update
+ *
+ * Reads the current benefit-definition.ts, parses the stateMachine and
+ * availableActions, and regenerates the ## Fluxos section in README.md
+ * with up-to-date Mermaid diagrams.
+ *
+ * Run manually or let the pre-commit hook handle it automatically.
+ */
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import benefitDefinition from '../../src/benefit-definition';
+
+const ACTION_LABELS: Record<string, string> = {
+  GRANT: 'Concessão de Benefício (GRANT)',
+  REVOKE: 'Revogação de Benefício (REVOKE)',
+  RECHARGE: 'Recarga de Benefício (RECHARGE)',
+  DEDUCTION: 'Dedução (DEDUCTION)',
+  GRANT_DEPENDENT: 'Concessão para Dependente (GRANT_DEPENDENT)',
+  REVOKE_DEPENDENT: 'Revogação de Dependente (REVOKE_DEPENDENT)',
+  BEFORE_ALL_RECHARGE: 'Pré-processamento de Recargas (BEFORE_ALL_RECHARGE)',
+  AFTER_ALL_RECHARGE: 'Pós-processamento de Recargas (AFTER_ALL_RECHARGE)',
+  DEDUCTION_FILE_INGESTION: 'Ingestão de Arquivo de Deduções (DEDUCTION_FILE_INGESTION)'
+};
+
+function generateMermaidDiagram(
+  states: Record<string, Record<string, string>>
+): string {
+  const lines: string[] = ['flowchart TD'];
+
+  // The starting state is usually REQUESTED_*, otherwise the first defined state
+  const firstState =
+    Object.keys(states).find((s) => s.startsWith('REQUESTED_')) ?? Object.keys(states)[0];
+
+  lines.push(`  START([Início]) --> ${firstState}`);
+
+  // Track all states that appear as transition targets
+  const allTargets = new Set<string>();
+
+  for (const [state, transitions] of Object.entries(states)) {
+    for (const [transitionType, targetState] of Object.entries(
+      transitions as Record<string, string>
+    )) {
+      lines.push(`  ${state} -->|${transitionType}| ${targetState}`);
+      allTargets.add(targetState);
+    }
+  }
+
+  // Terminal states = appear as targets but are not defined as source states
+  const terminalStates = [...allTargets].filter((s) => !(s in states));
+  for (const terminal of terminalStates) {
+    const isFailure = terminal.includes('FAILED') || terminal.includes('FAIL');
+    lines.push(`  ${terminal}([${terminal} ${isFailure ? '❌' : '✅'}])`);
+  }
+
+  return '```mermaid\n' + lines.join('\n') + '\n```';
+}
+
+function generateActionSection(
+  action: string,
+  states: Record<string, Record<string, string>>
+): string {
+  const label = ACTION_LABELS[action] ?? action;
+  const diagram = generateMermaidDiagram(states);
+  return `### ${label}\n\n${diagram}`;
+}
+
+const stateMachine = benefitDefinition.stateMachine as Record<
+  string,
+  Record<string, Record<string, string>>
+>;
+const availableActions = benefitDefinition.availableActions as readonly string[];
+
+// Only generate diagrams for actions that are:
+// 1. Listed in availableActions
+// 2. Defined in stateMachine
+const sections = Object.entries(stateMachine)
+  .filter(([action]) => availableActions.includes(action))
+  .map(([action, states]) => generateActionSection(action, states))
+  .join('\n\n');
+
+const newFluxosSection = `## Fluxos\n\n${sections}`;
+
+const readmePath = join(process.cwd(), 'README.md');
+const readme = readFileSync(readmePath, 'utf-8');
+
+// Replace everything between ## Fluxos and the next ## heading
+const updated = readme.replace(/## Fluxos[\s\S]*?(?=\n## )/, newFluxosSection + '\n');
+
+if (updated === readme) {
+  console.log('[benSDK] README.md: Fluxos section is already up to date');
+} else {
+  writeFileSync(readmePath, updated);
+  console.log('[benSDK] README.md updated with current state machine diagrams');
+}