cogfy-data-exchange 1.0.0

package/.github/workflows/tests.yml

@@ -0,0 +1,21 @@
+on: [push]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    timeout-minutes: 8
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - run: npm ci
+      - run: npm run build
+      - run: npm run lint
+      - run: npm run test

package/README.md

@@ -0,0 +1,176 @@
+# Cogfy Data Exchange
+
+Uma biblioteca TypeScript para definição e execução de fluxos de navegação fortemente tipados.
+
+---
+
+## Visão Geral
+
+O **cogfy-data-exchange** permite definir fluxos (flows) baseados em telas (screens) com:
+
+- Tipagem forte em tempo de compilação
+- Controle de navegação entre telas
+- Inferência automática de dados de entrada e saída
+- Engine simples para execução (`createFlow`)
+
+A ideia central é transformar um JSON de fluxo em uma máquina de estados tipada.
+
+---
+
+## Conceitos
+
+### Flow
+
+Um flow descreve:
+
+- `routing_model`: quais telas podem navegar para quais
+- `screens`: quais dados cada tela recebe/retorna
+
+```ts
+const flow = {
+  routing_model: {
+    SCREEN_A: ['SCREEN_B', 'SCREEN_C'],
+    SCREEN_B: ['SCREEN_D'],
+    SCREEN_C: ['SCREEN_D'],
+    SCREEN_D: []
+  },
+  screens: [
+    { id: 'SCREEN_A', data: { name: { type: 'string' } } },
+    { id: 'SCREEN_B', data: { age: { type: 'number' } } },
+    { id: 'SCREEN_C', data: { isActive: { type: 'boolean' } } },
+    {
+      id: 'SCREEN_D',
+      data: {
+        profile: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            age: { type: 'number' }
+          }
+        }
+      }
+    }
+  ]
+} as const
+```
+
+### Convenção de nomenclatura do trigger
+Os triggers de navegação devem seguir a convenção `screen.{SCREEN_ID}`. Por exemplo, para `SCREEN_A`, o trigger seria `screen.SCREEN_A`.
+
+---
+
+## Uso
+
+### 1. Criar o flow
+
+```ts
+import { createFlow } from 'cogfy-data-exchange'
+```
+
+### 2. Definir handlers
+
+```ts
+const engine = createFlow(flow, {
+  SCREEN_A: async (data) => {
+    // data: { name: string }
+
+    return {
+      screen: 'SCREEN_B',
+      data: { age: 30 }
+    }
+  },
+
+  SCREEN_B: async (data) => {
+    return {
+      screen: 'SCREEN_D',
+      data: {
+        profile: { name: 'John', age: 20 }
+      }
+    }
+  },
+
+  SCREEN_C: async (data) => {
+    return {
+      screen: 'SCREEN_D',
+      data: {
+        profile: { name: 'Jane', age: 25 }
+      }
+    }
+  },
+
+  SCREEN_D: async () => {
+    throw new Error('Fim do fluxo')
+  }
+})
+```
+
+### 3. Executar o flow
+
+```ts
+const result = await engine.dispatch('screen.SCREEN_A', { name: 'John' })
+
+// result:
+// {
+//   screen: 'SCREEN_B' | 'SCREEN_C'
+//   data: ...
+// }
+```
+
+---
+
+## Inferência de Tipos
+
+A biblioteca infere automaticamente os seguintes aspectos:
+
+**Entrada do handler**
+
+```ts
+SCREEN_A → { name: string }
+```
+
+**Próximas telas possíveis**
+
+```ts
+SCREEN_A → 'SCREEN_B' | 'SCREEN_C'
+```
+
+**Dados da próxima tela**
+
+```ts
+SCREEN_B → { age: number }
+```
+
+---
+
+## Garantias de Tipo
+
+A biblioteca garante em tempo de compilação:
+
+- Navegação restrita às telas válidas definidas no `routing_model`
+- Formato correto do campo `data` em cada transição
+- Implementação obrigatória de todos os handlers
+- Tipos sempre sincronizados com a definição do flow
+
+---
+
+## Exemplos Inválidos
+
+**Navegação inválida**
+
+```ts
+// Erro de tipo: SCREEN_D não é uma transição permitida a partir de SCREEN_A
+return {
+  screen: 'SCREEN_D',
+  data: {}
+}
+```
+
+**Data inválido**
+
+```ts
+// Erro de tipo: age deve ser do tipo number
+return {
+  screen: 'SCREEN_B',
+  data: { age: 'wrong' }
+}
+```

package/biome.json

@@ -0,0 +1,73 @@
+{
+	"assist": {
+		"actions": {
+			"source": {
+				"organizeImports": "on",
+				"useSortedAttributes": "on",
+				"useSortedKeys": "on",
+				"useSortedProperties": "on"
+			}
+		},
+		"enabled": true
+	},
+	"files": {
+		"ignoreUnknown": false,
+		"includes": [
+			"./**/*.ts",
+			"./**/*.tsx",
+			"./**/*.js",
+			"./**/*.jsx",
+			"./**/*.json",
+			"!**/build/*",
+			"!package.json"
+		]
+	},
+	"formatter": {
+		"enabled": true,
+		"formatWithErrors": false,
+		"indentStyle": "space",
+		"indentWidth": 2,
+		"lineEnding": "lf",
+		"lineWidth": 120
+	},
+	"javascript": {
+		"formatter": {
+			"arrowParentheses": "always",
+			"bracketSpacing": true,
+			"quoteProperties": "asNeeded",
+			"quoteStyle": "single",
+			"semicolons": "asNeeded",
+			"trailingCommas": "none"
+		}
+	},
+	"json": {
+		"formatter": {
+			"lineWidth": 150
+		}
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"correctness": {
+				"noUnreachableSuper": "error",
+				"noUnusedVariables": "warn"
+			},
+			"recommended": true,
+			"style": {
+				"noEnum": "on",
+				"useBlockStatements": {
+					"fix": "safe",
+					"level": "warn"
+				}
+			},
+			"suspicious": {
+				"noConstEnum": "off"
+			}
+		}
+	},
+	"vcs": {
+		"clientKind": "git",
+		"enabled": true,
+		"useIgnoreFile": true
+	}
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "cogfy-data-exchange",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc",
+    "lint": "biome lint",
+    "test": "vitest run"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "UNLICENSED",
+  "type": "module",
+  "devDependencies": {
+    "@biomejs/biome": "2.4.8",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/src/__tests__/create-flow.test.ts

@@ -0,0 +1,68 @@
+import { describe, test } from 'vitest'
+import { createFlow } from '../create-flow'
+import type { FlowJson } from '../types'
+
+const flow = {
+  routing_model: {
+    SCREEN_A: ['SCREEN_B', 'SCREEN_C'],
+    SCREEN_B: ['SCREEN_D'],
+    SCREEN_C: ['SCREEN_D'],
+    SCREEN_D: []
+  },
+  screens: [
+    { data: { name: { type: 'string' } }, id: 'SCREEN_A' },
+    { data: { age: { type: 'number' } }, id: 'SCREEN_B' },
+    { data: { isActive: { type: 'boolean' } }, id: 'SCREEN_C' },
+    {
+      data: {
+        profile: {
+          properties: {
+            age: { type: 'number' },
+            name: { type: 'string' }
+          },
+          type: 'object'
+        }
+      },
+      id: 'SCREEN_D'
+    }
+  ]
+} as const satisfies FlowJson
+
+describe('createFlow', () => {
+  test('should dispatch screens correctly', async ({ expect }) => {
+    const engine = createFlow(flow, {
+      SCREEN_A: async () => {
+        return {
+          data: { age: 30 },
+          screen: 'SCREEN_B'
+        }
+      },
+      SCREEN_B: async () => {
+        return {
+          data: {
+            profile: { age: 20, name: 'John' }
+          },
+          screen: 'SCREEN_D'
+        }
+      },
+      SCREEN_C: async () => {
+        return {
+          data: {
+            profile: { age: 25, name: 'Jane' }
+          },
+          screen: 'SCREEN_D'
+        }
+      },
+      SCREEN_D: async () => {
+        throw new Error('end')
+      }
+    })
+
+    const result = await engine.dispatch('screen.SCREEN_A', { name: 'John' })
+
+    expect(result).toEqual({
+      data: { age: 30 },
+      screen: 'SCREEN_B'
+    })
+  })
+})

package/src/create-flow.ts

@@ -0,0 +1,26 @@
+import type { ExtractScreen, FlowJson, NextResult, ScreenData, ScreenName, ScreenTrigger } from './types'
+
+type Handlers<F extends FlowJson> = {
+  [K in ScreenName<F>]: (data: ScreenData<F, K>) => Promise<NextResult<F, K>>
+}
+
+/**
+ * Creates a flow engine based on the provided flow definition and handlers.
+ * @param flow The flow definition, which includes the routing model and screen definitions.
+ * @param handlers An object mapping screen IDs to their corresponding handler functions. Each handler receives the data for its screen and returns a promise that resolves to the next result, which includes the next screen and its data.
+ * @returns An object with a `dispatch` method to trigger screen handlers and the original flow definition.
+ */
+export function createFlow<F extends FlowJson>(flow: F, handlers: Handlers<F>) {
+  return {
+    dispatch<T extends ScreenTrigger<ScreenName<F>>>(
+      trigger: T,
+      data: ScreenData<F, ExtractScreen<T, F>>
+    ): Promise<NextResult<F, ExtractScreen<T, F>>> {
+      const screen = trigger.replace('screen.', '') as ExtractScreen<T, F>
+
+      return handlers[screen](data)
+    },
+
+    flow
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './create-flow'
+export * from './types'

package/src/types/flow-json.ts

@@ -0,0 +1,15 @@
+export type FlowJsonDataValue =
+  | { type: 'string' }
+  | { type: 'number' }
+  | { type: 'boolean' }
+  | { type: 'object'; properties: Record<string, FlowJsonDataValue> }
+  | { type: 'array'; items: FlowJsonDataValue }
+
+export type FlowJsonData = Record<string, FlowJsonDataValue>
+
+export type FlowJsonScreenId = string
+
+export type FlowJson = {
+  routing_model: Record<FlowJsonScreenId, FlowJsonScreenId[]>
+  screens: { id: FlowJsonScreenId; data: FlowJsonData }[]
+}

package/src/types/index.ts

@@ -0,0 +1,7 @@
+export * from './flow-json'
+export * from './result'
+export * from './routing'
+export * from './schema'
+export * from './screen'
+export * from './screen-handler'
+export * from './trigger'

package/src/types/result.ts

@@ -0,0 +1,29 @@
+import type { FlowJson } from './flow-json'
+import type { NextScreens } from './routing'
+import type { ScreenData, ScreenName } from './screen'
+
+type ScreenErrorResult<S extends string> = {
+  screen: S
+  data: {
+    error_message: string
+  }
+}
+
+type FlowSuccessResult = {
+  screen: 'SUCCESS'
+  data: {
+    extension_message_response: {
+      params: Record<string, unknown> & { flow_token: string }
+    }
+  }
+}
+
+export type NextResult<F extends FlowJson, S extends ScreenName<F>> =
+  | {
+      [K in NextScreens<F, S>]: {
+        screen: K
+        data: ScreenData<F, K>
+      }
+    }[NextScreens<F, S>]
+  | ScreenErrorResult<S>
+  | FlowSuccessResult

package/src/types/routing.ts

@@ -0,0 +1,7 @@
+import type { FlowJson } from './flow-json'
+import type { ScreenName } from './screen'
+
+export type NextScreens<F extends FlowJson, S extends ScreenName<F>> = Extract<
+  F['routing_model'][S][number],
+  ScreenName<F>
+>

package/src/types/schema.ts

@@ -0,0 +1,13 @@
+export type FromSchema<S> = S extends { type: 'string' }
+  ? string
+  : S extends { type: 'number' }
+    ? number
+    : S extends { type: 'boolean' }
+      ? boolean
+      : S extends { type: 'array'; items: infer I }
+        ? FromSchema<I>[]
+        : S extends { type: 'object'; properties: infer P }
+          ? { [K in keyof P]: FromSchema<P[K]> }
+          : S extends Record<string, unknown>
+            ? { [K in keyof S]: FromSchema<S[K]> }
+            : unknown

package/src/types/screen-handler.ts

@@ -0,0 +1,7 @@
+import type { FlowJson } from './flow-json'
+import type { NextResult } from './result'
+import type { ScreenData, ScreenName } from './screen'
+
+export type ScreenHandler<F extends FlowJson, S extends ScreenName<F>> = {
+  handle(data: ScreenData<F, S>): Promise<NextResult<F, S>>
+}

package/src/types/screen.ts

@@ -0,0 +1,11 @@
+import type { FlowJson } from './flow-json'
+import type { FromSchema } from './schema'
+
+export type ScreenName<F extends FlowJson> = Extract<keyof F['routing_model'], string>
+
+export type ScreenSchema<F extends FlowJson, Id extends ScreenName<F>> = Extract<
+  F['screens'][number],
+  { id: Id }
+>['data']
+
+export type ScreenData<F extends FlowJson, Id extends ScreenName<F>> = FromSchema<ScreenSchema<F, Id>>

package/src/types/trigger.ts

@@ -0,0 +1,9 @@
+import type { FlowJson } from './flow-json'
+import type { ScreenName } from './screen'
+
+export type ScreenTrigger<S extends string> = `screen.${S}`
+
+export type ExtractScreen<T extends string, F extends FlowJson> = Extract<
+  T extends `screen.${infer S}` ? S : never,
+  ScreenName<F>
+>

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "commonjs",
+    "outDir": "dist",
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "es2024"
+  },
+  "exclude": []
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    exclude: ['dist/**']
+  }
+})