WIP: Generative docs

README.md

@@ -37,7 +37,7 @@ Full documentation is located in the [`docs/`](docs/) folder:
 - [GLS Action Overview](docs/Actions/GLS/overview.md)
 - [GLS Configuration](docs/Actions/GLS/configs.md)
 - [GLS Functions](docs/Actions/GLS/functions.md)
-- [GLS Types](docs/Actions/GLS/types.md)
+- [GLS Types](docs/Actions/GLS/types.mdx)
 - [GLS Events](docs/Actions/GLS/events.md)
 - [Common Use Cases](docs/Actions/GLS/use-cases.md)
 - [Troubleshooting & Community Support](docs/Actions/GLS/troubleshooting.md)

actions/gls-action/package.json

@@ -9,6 +9,10 @@
     "build": "vite build",
     "lint": "eslint .",
     "test": "vitest run",
-    "start": "node dist/main.js"
+    "start": "node dist/main.js",
+    "docs:generate": "npm run build && node dist/generateTypes.js > ../../docs/Actions/GLS/types.mdx"
+  },
+  "dependencies": {
+    "ts-morph": "^27.0.2"
   }
 }

actions/gls-action/scripts/generateTypes.ts

@@ -0,0 +1,222 @@
+import {loadAllDefinitions} from "../src/helpers";
+import {
+    HerculesActionConfigurationDefinition,
+    HerculesDataType, HerculesFlowType, HerculesRegisterFunctionParameter,
+} from "@code0-tech/hercules";
+import {Project, SymbolFlags, Type} from "ts-morph";
+
+
+const state = {
+    dataTypes: [] as HerculesDataType[],
+    actionConfigurationDefinitions: [] as HerculesActionConfigurationDefinition[],
+    runtimeFunctions: [] as HerculesRegisterFunctionParameter[],
+    flowTypes: [] as HerculesFlowType[]
+}
+
+
+async function run() {
+    await loadAllDefinitions({
+        onError: () => {
+        },
+        connect: () => Promise.resolve([]),
+        dispatchEvent: () => Promise.resolve(),
+        getProjectActionConfigurations: () => [],
+        config: {
+            authToken: "",
+            aquilaUrl: "",
+            version: "",
+            actionId: ""
+        },
+        fullyConnected: () => false,
+        registerDataTypes: (...dataTypes) => {
+            state.dataTypes = [
+                ...dataTypes,
+                ...state.dataTypes
+            ]
+            return Promise.resolve()
+        },
+        registerConfigDefinitions: (...actionConfigurations) => {
+            state.actionConfigurationDefinitions = [
+                ...actionConfigurations,
+                ...state.actionConfigurationDefinitions
+            ]
+            return Promise.resolve()
+        },
+        registerFunctionDefinitions: (...functionDefinitions) => {
+            state.runtimeFunctions = [
+                ...functionDefinitions,
+                ...state.runtimeFunctions
+            ]
+            return Promise.resolve()
+        },
+        registerFlowTypes: (...flowTypes) => {
+            state.flowTypes = [
+                ...state.flowTypes,
+                ...flowTypes
+            ]
+            return Promise.resolve()
+        }
+
+    })
+}
+
+run().then(async () => {
+    console.log(`---
+title: Datatypes
+description: All data types registered by the GLS Action — field references and descriptions.
+---
+import {TypeTable} from "fumadocs-ui/components/type-table";
+
+# GLS Action Types
+
+The GLS Action registers the following data types with the Hercules platform. These types are used as inputs and outputs
+of the GLS functions and can be referenced in your flows.
+
+--- 
+    `)
+    state.dataTypes.forEach(value => {
+        value.type = `export type ${value.identifier} = ${value.type}`
+            .replace(/ \| undefined/g, "")
+
+
+        function breakDown(
+            typeName: string,
+            code: string
+        ): Record<string, string> {
+            const map: Record<string, string> = {};
+
+            const project = new Project({useInMemoryFileSystem: true});
+            const sourceFile = project.createSourceFile("example.ts", code);
+
+            const typeAlias = sourceFile.getTypeAliasOrThrow(typeName);
+            let rootType = typeAlias.getType();
+
+            if (rootType.isArray()) {
+                rootType = rootType.getArrayElementTypeOrThrow();
+            }
+
+            function buildType(type: Type, currentName: string): string {
+                const props = type.getProperties();
+
+                const lines: string[] = [];
+
+                props.forEach(symbol => {
+                    const name = symbol.getName();
+                    const decl = symbol.getDeclarations()[0];
+                    if (!decl) return;
+
+
+                    let propType = symbol.getTypeAtLocation(decl);
+
+                    // unwrap arrays
+                    let isArray = false;
+                    if (propType.isArray()) {
+                        propType = propType.getArrayElementTypeOrThrow();
+                        isArray = true;
+                    }
+
+                    let typeText: string;
+
+                    if (propType.getText().startsWith("{")) {
+                        const newName = `${currentName}$${name}`;
+
+                        // recurse first
+                        const nestedType = buildType(propType, newName);
+
+                        map[newName] = `export type ${newName} = ${nestedType};`;
+
+                        typeText = isArray ? `${newName}[]` : newName;
+                    } else {
+                        typeText = propType.getText(decl);
+                    }
+
+                    // JSDoc
+                    const jsDocs = (decl as any).getJsDocs?.()
+                        ?.map(d => d.getText())
+                        .join("\n");
+
+                    const docPrefix = jsDocs ? `${jsDocs}\n` : "";
+
+                    lines.push(
+                        `${docPrefix}${name}${symbol.hasFlags(SymbolFlags.Optional) ? "?" : ""}: ${typeText};`
+                    );
+                });
+
+                return `{\n${lines.map(l => "    " + l).join("\n")}\n}`;
+            }
+
+            const finalType = buildType(rootType, typeName);
+
+            map[typeName] = `export type ${typeName} = ${finalType};`;
+
+            return map;
+        }
+
+
+        const broke = breakDown(value.identifier, value.type)
+        const entries = Object.entries(broke).reverse();
+
+        for (const [key, val] of entries) {
+            let typeString = `
+            `
+
+            const project = new Project({useInMemoryFileSystem: true});
+            const sourceFile = project.createSourceFile("example.ts", val);
+
+
+            const typeAlias = sourceFile.getTypeAliasOrThrow(key);
+
+
+            let type = typeAlias.getType()
+            const array = typeAlias.getType().isArray()
+            if (array) {
+                type = type.getArrayElementTypeOrThrow()
+            }
+
+            type.getProperties().forEach(property => {
+                const name = property.getName();
+
+                const currType = property.getTypeAtLocation(typeAlias);
+                const currTypeText = currType.getText();
+
+                const docs = {
+                    description: "No description set",
+                    deprecated: false,
+                    default: undefined,
+                    link: undefined
+                }
+
+
+                property.getJsDocTags().forEach(info => {
+                    info.getText().forEach(part => {
+                        docs[info.getName()] = part.text.trim()
+                    })
+                })
+                if (currTypeText.startsWith("GLS_")) {
+                    docs.link = currTypeText.toLowerCase()
+                        .replace(/-/g, "_")
+                        .replace(/\$/g, "")
+                        .replace("[]", "")
+                }
+                typeString += `${name}: {
+                description: '${docs.description}',
+                deprecated: ${docs.deprecated},
+                required: ${!property.isOptional()}, ${docs.link ? `\ntypeDescriptionLink: '#${docs.link}',` : ""}
+                type: '${currTypeText}', ${docs.default ? `\ndefault: ${docs.default}` : ""} 
+            },
+            `
+
+            })
+
+            const table = `<TypeTable type={{${typeString}}}
+/>`
+            console.log(`# ${key}`)
+            console.log(table)
+        }
+        // console.log(`
+// # ${value.identifier} ${array ? "[]" : ""}
+//         `)
+//         console.log(table)
+    })
+
+})

actions/gls-action/src/index.ts

@@ -18,6 +18,7 @@ async function main() {
         console.error(error)
     }
 }
+
 main().catch(err => {
     console.error(err)
     process.exit(1)

actions/gls-action/src/types/glsAddress.ts

@@ -3,19 +3,44 @@ import z from "zod"
 import {singleZodSchemaToTypescriptDef} from "../helpers";
 
 export const AddressSchema = z.object({
-    Name1: z.string().max(40),
-    Name2: z.string().max(40).optional(),
-    Name3: z.string().max(40).optional(),
-    CountryCode: z.string().max(2),
-    Province: z.string().max(40).optional(),
-    City: z.string().max(40),
-    Street: z.string().min(4),
-    StreetNumber: z.string().max(40).optional(),
-    ContactPerson: z.string().max(40).min(6).optional(),
-    FixedLinePhonenumber: z.string().max(35).min(4).optional(),
-    MobilePhonenumber: z.string().max(35).min(4).optional(),
-    eMail: z.string().max(80).optional(),
-    ZIPCode: z.string().max(10),
+    Name1: z.string().max(40).describe(`
+    @description Primary name line (person or company). Max 40 characters.
+    `),
+    Name2: z.string().max(40).optional().describe(`
+    @description Optional second name line (e.g., department or additional identifier). Max 40 characters.
+    `),    Name3: z.string().max(40).optional().describe(`
+    @description Optional third name line for extended address details. Max 40 characters.
+    `),
+    CountryCode: z.string().max(2).describe(`
+    @description Two-letter ISO country code (e.g., DE, US).
+    `),
+    Province: z.string().max(40).optional().describe(`
+    @description State, province, or region. Optional field. Max 40 characters.
+    `),
+    City: z.string().max(40).describe(`
+    @description City or locality name. Max 40 characters.
+    `),
+    Street: z.string().min(4).describe(`
+    @description Street name. Minimum 4 characters required.
+    `),
+    StreetNumber: z.string().max(40).optional().describe(`
+    @description House or building number. Optional field. Max 40 characters.
+    `),
+    ContactPerson: z.string().max(40).min(6).optional().describe(`
+    @description Full name of a contact person. Optional field. Must be between 6 and 40 characters.
+    `),
+    FixedLinePhonenumber: z.string().max(35).min(4).optional().describe(`
+    @description Landline phone number. Optional field. Must be between 4 and 35 characters.
+    `),
+    MobilePhonenumber: z.string().max(35).min(4).optional().describe(`
+    @description Mobile phone number. Optional field. Must be between 4 and 35 characters.
+    `),
+    eMail: z.string().max(80).optional().describe(`
+    @description Email address. Optional field. Max 80 characters.
+    `),
+    ZIPCode: z.string().max(10).describe(`
+    @description Postal or ZIP code. Max 10 characters.
+    `),
 })
 export type AddressSchema = z.infer<typeof AddressSchema>
 

actions/gls-action/src/types/glsEndOfDayRequest.ts

@@ -1,5 +1,5 @@
 import {ActionSdk} from "@code0-tech/hercules";
-import {singleZodSchemaToTypescriptDef} from "../helpers";
+import {singleZodSchemaToTypescriptDef, zodSchemaToTypescriptDefs} from "../helpers";
 import z from "zod";
 import {AddressSchema} from "./glsAddress";
 
@@ -50,10 +50,13 @@ export default (sdk: ActionSdk) => {
         },
         {
             identifier: "GLS_END_OF_DAY_RESPONSE_DATA",
-            type: singleZodSchemaToTypescriptDef(
+            type: zodSchemaToTypescriptDefs(
                 "GLS_END_OF_DAY_RESPONSE_DATA",
-                EndOfDayResponseDataSchema
-            ),
+                EndOfDayResponseDataSchema,
+                {
+                    GLS_ADDRESS: AddressSchema
+                }
+            ).get("GLS_END_OF_DAY_RESPONSE_DATA")!,
             name: [
                 {
                     code: "en-US",

actions/gls-action/src/types/glsShipment.ts

@@ -17,7 +17,7 @@ export const ShipmentSchema = z.object({
     Consignee: ConsigneeSchema,
     Shipper: ShipperSchema.optional(),
     Carrier: z.enum(["ROYALMAIL"]).optional(),
-    ShipmentUnit: ShipmentUnitSchema,
+    ShipmentUnit: z.lazy(() => ShipmentUnitSchema),
     Service: z.lazy(() => ShipmentServiceSchema),
     Return: z.object({
         Address: AddressSchema
@@ -30,7 +30,7 @@ export const InternalShipmentSchma = ShipmentSchema.extend({
     Middleware: z.string().max(40),
     Shipper: InternalShipperSchema,
     Service: z.lazy(() => InternalShipmentServiceSchema),
-    ShipmentUnit: InternalShipmentUnitSchema
+    ShipmentUnit: z.lazy(() => InternalShipmentUnitSchema)
 })
 
 export default (sdk: ActionSdk) => {

actions/gls-action/src/types/glsShipmentService.ts

@@ -1,8 +1,5 @@
 import z from "zod";
 import {AddressSchema} from "./glsAddress";
-import {zodSchemaToTypescriptDefs} from "../helpers";
-import {ShipmentSchema} from "./glsShipment";
-import {ActionSdk} from "@code0-tech/hercules";
 
 
 export const ShipmentServiceSchema = z.array(z.object({
@@ -185,33 +182,3 @@ export const InternalShipmentServiceSchema = z.array(z.object({
         serviceName: z.string().default("service_Saturday"),
     }).optional(),
 })).optional()
-
-export default (sdk: ActionSdk) => {
-    return sdk.registerDataTypes(
-        {
-            identifier: "GLS_SHIPMENT_SERVICE",
-            type: zodSchemaToTypescriptDefs(
-                "XXX",
-                ShipmentSchema,
-                {
-                    GLS_SHIPMENT_SERVICE: ShipmentServiceSchema,
-                }
-            ).get("GLS_SHIPMENT_SERVICE")!, // Hacky way because shipment service is defined as an array
-            name: [
-                {
-                    code: "en-US",
-                    content: "Shipment Service"
-                }
-            ],
-            displayMessage: [
-                {
-                    code: "en-US",
-                    content: "Shipment Service"
-                }
-            ],
-            linkedDataTypes: [
-                "GLS_ADDRESS"
-            ]
-        },
-    )
-}