From 1a9b8285cd2129712b4fb216bcdff931cfe0882a Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Sun, 29 Mar 2026 21:47:43 +0200 Subject: [PATCH 01/17] First progress in generating docs --- actions/gls-action/package.json | 3 +- actions/gls-action/scripts/generateTypes.ts | 132 ++++ actions/gls-action/src/types/glsAddress.ts | 69 +- .../src/types/glsEndOfDayRequest.ts | 11 +- actions/gls-action/src/types/glsShipment.ts | 4 +- .../src/types/glsShipmentService.ts | 33 - actions/gls-action/vite.config.ts | 1 + docs/Actions/GLS/types.md | 434 ------------- docs/Actions/GLS/types.mdx | 603 ++++++++++++++++++ package-lock.json | 18 +- package.json | 3 +- tsconfig.base.json | 4 +- 12 files changed, 816 insertions(+), 499 deletions(-) create mode 100644 actions/gls-action/scripts/generateTypes.ts delete mode 100644 docs/Actions/GLS/types.md create mode 100644 docs/Actions/GLS/types.mdx diff --git a/actions/gls-action/package.json b/actions/gls-action/package.json index 1e8868d..106637b 100644 --- a/actions/gls-action/package.json +++ b/actions/gls-action/package.json @@ -9,6 +9,7 @@ "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" } } diff --git a/actions/gls-action/scripts/generateTypes.ts b/actions/gls-action/scripts/generateTypes.ts new file mode 100644 index 0000000..aea98d1 --- /dev/null +++ b/actions/gls-action/scripts/generateTypes.ts @@ -0,0 +1,132 @@ +import {loadAllDefinitions} from "../src/helpers"; +import { + HerculesActionConfigurationDefinition, + HerculesDataType, HerculesFlowType, HerculesRegisterFunctionParameter, +} from "@code0-tech/hercules"; + + +const state = { + dataTypes: [] as HerculesDataType[], + actionConfigurationDefinitions: [] as HerculesActionConfigurationDefinition[], + runtimeFunctions: [] as HerculesRegisterFunctionParameter[], + flowTypes: [] as HerculesFlowType[] +} + + +async function run() { + await loadAllDefinitions({ + onError: handler => { + }, + connect: options => Promise.resolve([]), + dispatchEvent: (event, payload) => 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) => { + return Promise.resolve() + } + + }) +} + +run().then(async () => { + let typeContent = `--- +title: Datatypes +description: All data types registered by the GLS Action — field references and descriptions. +--- + +# 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, "") + .replace(/\/\*\*/g, "/**\n") + .replace(/\*\//g, "\n**/") + .replace( + /(\w+)(\?)?:\s*(GLS_\w+);/g, + (match, name, optionalMark, gls) => { + if (optionalMark) { + return `/** + Optional. + @fumadocsHref #type-table-temp.ts-${gls} +**/ +${name}: ${gls}`; + } + + return `/** + @fumadocsHref #type-table-temp.ts-${gls} +**/ +${name}: ${gls}`; + } + ); + + let array = false + if (value.type.endsWith("[];")) { + value.type = value.type.slice(0, -3) + ";" + array = true + } + + typeContent += ` +# ${value.identifier}${array ? " (array)" : ""} + + + +` + }) + typeContent = typeContent.replace(" | undefined", "") + + console.log(typeContent) +}) + + + + + + + + + + + + + + + + + diff --git a/actions/gls-action/src/types/glsAddress.ts b/actions/gls-action/src/types/glsAddress.ts index c75eb2c..4d76bc6 100644 --- a/actions/gls-action/src/types/glsAddress.ts +++ b/actions/gls-action/src/types/glsAddress.ts @@ -3,19 +3,62 @@ 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(` + Primary name line (person or company). + Max 40 characters. + `), + Name2: z.string().max(40).optional().describe(` + Optional second name line (e.g., department or additional identifier). + Max 40 characters. + `), Name3: z.string().max(40).optional().describe(` + Optional third name line for extended address details. + Max 40 characters. + `), + CountryCode: z.string().max(2).describe(` + Two-letter ISO country code (e.g., DE, US). + `), + Province: z.string().max(40).optional().describe(` + State, province, or region. + Optional field. + Max 40 characters. + `), + City: z.string().max(40).describe(` + City or locality name. + Max 40 characters. + `), + Street: z.string().min(4).describe(` + Street name. + Minimum 4 characters required. + `), + StreetNumber: z.string().max(40).optional().describe(` + House or building number. + Optional field. + Max 40 characters. + `), + ContactPerson: z.string().max(40).min(6).optional().describe(` + Full name of a contact person. + Optional field. + Must be between 6 and 40 characters. + `), + FixedLinePhonenumber: z.string().max(35).min(4).optional().describe(` + Landline phone number. + Optional field. + Must be between 4 and 35 characters. + `), + MobilePhonenumber: z.string().max(35).min(4).optional().describe(` + Mobile phone number. + Optional field. + Must be between 4 and 35 characters. + `), + eMail: z.string().max(80).optional().describe(` + Email address. + Optional field. + Max 80 characters. + `), + ZIPCode: z.string().max(10).describe(` + Postal or ZIP code. + Max 10 characters. + `), }) export type AddressSchema = z.infer diff --git a/actions/gls-action/src/types/glsEndOfDayRequest.ts b/actions/gls-action/src/types/glsEndOfDayRequest.ts index 50f4964..81b62bb 100644 --- a/actions/gls-action/src/types/glsEndOfDayRequest.ts +++ b/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", diff --git a/actions/gls-action/src/types/glsShipment.ts b/actions/gls-action/src/types/glsShipment.ts index 1e328f2..2bae894 100644 --- a/actions/gls-action/src/types/glsShipment.ts +++ b/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) => { diff --git a/actions/gls-action/src/types/glsShipmentService.ts b/actions/gls-action/src/types/glsShipmentService.ts index 5f85514..c65ccf1 100644 --- a/actions/gls-action/src/types/glsShipmentService.ts +++ b/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" - ] - }, - ) -} diff --git a/actions/gls-action/vite.config.ts b/actions/gls-action/vite.config.ts index f584efa..f258811 100644 --- a/actions/gls-action/vite.config.ts +++ b/actions/gls-action/vite.config.ts @@ -10,6 +10,7 @@ export default defineConfig({ rollupOptions: { input: { main: resolve(__dirname, 'src/index.ts'), + generateTypes: resolve(__dirname, 'scripts/generateTypes.ts') }, external: [ 'fs', diff --git a/docs/Actions/GLS/types.md b/docs/Actions/GLS/types.md deleted file mode 100644 index fd3af33..0000000 --- a/docs/Actions/GLS/types.md +++ /dev/null @@ -1,434 +0,0 @@ ---- -title: Datatypes -description: All data types registered by the GLS Action — field references and descriptions. ---- - -# 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. - ---- - -## `GLS_ADDRESS` - -Represents a physical address used for consignee, shipper, and return addresses. - -**Used by:** `GLS_CONSIGNEE`, `GLS_SHIPPER`, `GLS_SHIPMENT_SERVICE` (Exchange, DeliveryAtWork, etc.) - -| Field | Type | Required | Constraints | Description | -|------------------------|--------|----------|---------------|--------------------------------------------| -| `Name1` | string | **Yes** | max 40 | Primary name (person or company) | -| `Name2` | string | No | max 40 | Additional name line (e.g. department) | -| `Name3` | string | No | max 40 | Additional name line (e.g. c/o) | -| `CountryCode` | string | **Yes** | max 2 | ISO alpha-2 country code (e.g. `DE`, `FR`) | -| `Province` | string | No | max 40 | State or province | -| `City` | string | **Yes** | max 40 | City name | -| `Street` | string | **Yes** | min 4 | Street name | -| `StreetNumber` | string | No | max 40 | House/building number | -| `ContactPerson` | string | No | min 6, max 40 | Contact person name | -| `FixedLinePhonenumber` | string | No | min 4, max 35 | Landline phone number | -| `MobilePhonenumber` | string | No | min 4, max 35 | Mobile phone number | -| `eMail` | string | No | max 80 | Email address | -| `ZIPCode` | string | **Yes** | max 10 | Postal/ZIP code | - ---- - -## `GLS_CONSIGNEE` - -Represents the recipient of a shipment. - -**Used by:** `GLS_SHIPMENT` - -**Linked types:** `GLS_ADDRESS` - -| Field | Type | Required | Constraints | Description | -|---------------|-----------------------------|----------|-------------|-------------------------------------| -| `ConsigneeID` | string | No | max 40 | Your internal customer/consignee ID | -| `CostCenter` | string | No | max 80 | Cost center for billing | -| `Category` | `"BUSINESS"` \| `"PRIVATE"` | No | — | Type of recipient | -| `AddressSchema` | GLS_ADDRESS | **Yes** | — | Physical delivery address | - ---- - -## `GLS_SHIPPER` - -Represents the sender of a shipment. - -**Used by:** `GLS_SHIPMENT`, action configuration - -**Linked types:** `GLS_ADDRESS` - -| Field | Type | Required | Description | -|-----------------------------|-------------|----------|-------------------------------------------| -| `AddressSchema` | GLS_ADDRESS | No | Primary shipper address | -| `AlternativeShipperAddress` | GLS_ADDRESS | No | Alternative address to print on the label | - -> **Note:** When used in the configuration (`shipper`), the action automatically includes the `ContactID` from the -`contact_id` configuration value. - ---- - -## `GLS_UNIT_SERVICE` - -An optional array of value-added services applied to an individual shipment unit (parcel). - -**Used by:** `GLS_SHIPMENT_UNIT` - -Each element is an object with one or more of the following optional fields: - -| Service field | Description | -|---------------------|----------------------------------------------------------------------------------| -| `Cash` | Cash on delivery — `Reason` (max 160), `Amount` (min 1), `Currency` (3 chars) | -| `AddonLiability` | Additional liability insurance — `Amount`, `Currency`, `ParcelContent` (max 255) | -| `HazardousGoods` | Hazardous goods declaration — array of `{ Weight, GLSHazNo (max 8) }` | -| `ExWorks` | Ex-works shipping terms | -| `LimitedQuantities` | Limited quantities of dangerous goods — optional `Weight` | - ---- - -## `GLS_SHIPMENT_UNIT` - -Represents a single parcel within a shipment. A shipment may contain multiple units. - -**Used by:** `GLS_SHIPMENT`, `GLS_SHIPMENT_WITHOUT_SERVICES` - -**Linked types:** `GLS_UNIT_SERVICE` - -| Field | Type | Required | Constraints | Description | -|-------------------------|------------------|----------|-------------|---------------------------------| -| `Weight` | number | **Yes** | 0.10–99 kg | Weight of the parcel | -| `ShipmentUnitReference` | string | No | max 40 | Your internal parcel reference | -| `PartnerParcelNumber` | string | No | max 50 | Partner-assigned number | -| `Note1` | string | No | max 50 | Label note line 1 | -| `Note2` | string | No | max 50 | Label note line 2 | -| `Service` | GLS_UNIT_SERVICE | No | — | Unit-level value-added services | - ---- - -## `GLS_SHIPMENT_SERVICE` - -An optional array of shipment-level services. Shipment creation functions automatically populate this based on which -function you call. - -**Used by:** `GLS_SHIPMENT` - -Each element is an object with one of the following service fields: - -| Service | Parameters | Description | -|------------------------|------------------------------------------------------------------------------------------|------------------------------------| -| `ShopDelivery` | `ParcelShopID` (max 50) | Delivery to a GLS Parcel Shop | -| `ShopReturn` | `NumberOfLabels`, `ReturnQR?` | Return from a Parcel Shop | -| `Exchange` | `AddressSchema` (GLS_ADDRESS), `ExpectedWeight?` | Exchange delivery and pickup | -| `DeliveryAtWork` | `RecipientName`, `Building`, `Floor`, `Room?`, `Phonenumber?`, `AlternateRecipientName?` | Workplace delivery | -| `Deposit` | `PlaceOfDeposit` (max 121) | Deposit without signature | -| `IdentPin` | `PIN` (max 4), `Birthdate?` | PIN-based identity check | -| `Ident` | `Birthdate`, `Firstname`, `Lastname`, `Nationality` (max 2) | Full identity check | -| `PickAndShip` | `PickupDate` | GLS picks up from consignee | -| `FlexDeliveryService` | — | Recipient can redirect delivery | -| `SignatureService` | — | Signature required on delivery | -| `Guaranteed24Service` | — | 24-hour guaranteed delivery | -| `AddresseeOnlyService` | — | Delivery to named addressee only | -| `TyreService` | — | Tyre/wheel delivery service | -| `EOB` | — | End of Business (next working day) | -| `SaturdayService` | — | Saturday delivery | -| `Saturday1000Service` | — | Saturday by 10:00 | -| `Saturday1200Service` | — | Saturday by 12:00 | - ---- - -## `GLS_SHIPMENT` - -The complete shipment object including all services. - -**Used by:** `GLS_VALIDATE_SHIPMENT_REQUEST_DATA` - -**Linked types:** `GLS_CONSIGNEE`, `GLS_SHIPPER`, `GLS_SHIPMENT_UNIT`, `GLS_SHIPMENT_SERVICE`, `GLS_ADDRESS` - -| Field | Type | Required | Description | -|-----------------------------|---------------------------|----------|--------------------------------------------------| -| `Product` | `"PARCEL"` \| `"EXPRESS"` | **Yes** | Shipment product type | -| `ConsigneeSchema` | GLS_CONSIGNEE | **Yes** | Recipient details | -| `ShipperSchema` | GLS_SHIPPER | **Yes** | Sender details | -| `ShipmentUnit` | GLS_SHIPMENT_UNIT[] | **Yes** | Array of parcels (min 1) | -| `Service` | GLS_SHIPMENT_SERVICE | No | Shipment-level services | -| `ShipmentReference` | string (max 40) | No | Your internal shipment reference | -| `ShipmentDate` | date | No | Shipment date (defaults to today) | -| `IncotermCode` | integer (max 99) | No | International commerce terms code | -| `Identifier` | string (max 40) | No | Additional identifier | -| `ExpressAltDeliveryAllowed` | boolean | No | Allow alternative delivery for express shipments | -| `Carrier` | `"ROYALMAIL"` | No | Override carrier (UK only) | -| `Return.AddressSchema` | GLS_ADDRESS | No | AddressSchema for return shipments | - ---- - -## `GLS_SHIPMENT_WITHOUT_SERVICES` - -The shipment object without the `Service` field. Used as input to all shipment creation functions — the service is added -automatically based on which function you call. - -**Linked types:** `GLS_SHIPMENT` - -Same fields as `GLS_SHIPMENT` except `Service` is omitted. - ---- - -## `GLS_PRINTING_OPTIONS` - -Configures how shipping labels are generated. - -| Field | Type | Required | Description | -|---------------------------------|--------|----------|----------------------------------------------------------------------------------------------------------| -| `ReturnLabels.TemplateSet` | enum | **Yes** | Label template to use | -| `ReturnLabels.LabelFormat` | enum | **Yes** | Output file format | -| `useDefault` | string | No | If set to `"Default"`, uses the default printing options configured in GLS instead of the specified ones | -| `DefinePrinter.LabelPrinter` | string | No | Specify the printer name, only backend printers are valid | -| `DefinePrinter.DocumentPrinter` | string | no | Specify the document printer name, only backend printers are valid | - -**Template sets:** `NONE`, `D_200`, `PF_4_I`, `PF_4_I_200`, `PF_4_I_300`, `PF_8_D_200`, `T_200_BF`, `T_300_BF`, -`ZPL_200`, `ZPL_200_TRACKID_EAN_128`, `ZPL_200_TRACKID_CODE_39`, `ZPL_200_REFNO_EAN_128`, `ZPL_200_REFNO_CODE_39`, -`ZPL_300`, `ZPL_300_TRACKID_EAN_128`, `ZPL_300_TRACKID_CODE_39`, `ZPL_300_REFNO_EAN_128`, `ZPL_300_REFNO_CODE_39` - -**Label formats:** `PDF`, `ZEBRA`, `INTERMEC`, `DATAMAX`, `TOSHIBA`, `PNG` - ---- - -## `GLS_RETURN_OPTIONS` - -Controls whether the GLS API includes print data and routing info in the response. - -| Field | Type | Default | Description | -|---------------------|---------|---------|------------------------------------------| -| `ReturnPrintData` | boolean | `true` | Include base64-encoded label in response | -| `ReturnRoutingInfo` | boolean | `true` | Include routing information in response | - -> Set both to `false` if you only need the `TrackID` and don't need the label data immediately. - ---- - -## `GLS_CUSTOM_CONTENT` - -Customizes what appears on the printed shipping label. - -| Field | Type | Required | Description | -|----------------------|--------------------------------------------|----------|--------------------------------------| -| `CustomerLogo` | string | **Yes** | Base64-encoded logo image | -| `BarcodeContentType` | `"TRACK_ID"` \| `"GLS_SHIPMENT_REFERENCE"` | **Yes** | What to encode in the custom barcode | -| `Barcode` | string | No | Custom barcode value | -| `BarcodeType` | `"EAN_128"` \| `"CODE_39"` | No | Barcode symbology | -| `HideShipperAddress` | boolean | No | Hide shipper address on label | - ---- - -## `GLS_CREATE_PARCELS_RESPONSE` - -The response returned by all shipment creation functions. - -| Field | Type | Description | -|--------------------------------------------------------------|------------------|------------------------------------------| -| `CreatedShipment.ShipmentReference` | string[] | Your shipment references | -| `CreatedShipment.ParcelData[].TrackID` | string (8 chars) | GLS tracking ID — use to track or cancel | -| `CreatedShipment.ParcelData[].ParcelNumber` | string | GLS parcel number | -| `CreatedShipment.ParcelData[].Barcodes.Primary2D` | string | 2D barcode data | -| `CreatedShipment.ParcelData[].Barcodes.Secondary2D` | string | Secondary 2D barcode | -| `CreatedShipment.ParcelData[].Barcodes.Primary1D` | string | 1D barcode data | -| `CreatedShipment.ParcelData[].Barcodes.Primary1DPrint` | boolean | Whether to print 1D barcode | -| `CreatedShipment.ParcelData[].RoutingInfo.Tour` | string | Delivery tour identifier | -| `CreatedShipment.ParcelData[].RoutingInfo.FinalLocationCode` | string | Final delivery depot | -| `CreatedShipment.ParcelData[].RoutingInfo.HubLocation` | string | Hub location code | -| `CreatedShipment.ParcelData[].RoutingInfo.LastRoutingDate` | date | Last valid routing date | -| `CreatedShipment.PrintData[].Data` | string | Base64-encoded label | -| `CreatedShipment.PrintData[].LabelFormat` | enum | Format of the label | -| `CreatedShipment.CustomerID` | string | GLS customer identifier | -| `CreatedShipment.PickupLocation` | string | Depot where parcel will be picked up | -| `CreatedShipment.GDPR` | string[] | GDPR-related references | - ---- - -## `GLS_CANCEL_SHIPMENT_REQUEST_DATA` - -Input for the `cancelShipment` function. - -| Field | Type | Required | Description | -|-----------|--------|----------|-------------------------------------------| -| `TrackID` | string | **Yes** | GLS tracking ID of the shipment to cancel | - ---- - -## `GLS_CANCEL_SHIPMENT_RESPONSE_DATA` - -Response from the `cancelShipment` function. - -| Field | Type | Description | -|-----------|-----------------------------------------------------------------------|------------------------------------| -| `TrackID` | string | The tracking ID that was cancelled | -| `result` | `"CANCELLED"` \| `"CANCELLATION_PENDING"` \| `"SCANNED"` \| `"ERROR"` | Result of the cancellation | - ---- - -## `GLS_ALLOWED_SERVICES_REQUEST_DATA` - -Input for the `getAllowedServices` function. - -| Field | Type | Required | Description | -|---------------------------|-----------------|----------|-----------------------------------| -| `Source.CountryCode` | string (max 2) | **Yes** | Origin country code | -| `Source.ZIPCode` | string (max 10) | **Yes** | Origin ZIP/postal code | -| `Destination.CountryCode` | string (max 2) | **Yes** | Destination country code | -| `Destination.ZIPCode` | string (max 10) | **Yes** | Destination ZIP/postal code | -| `ContactID` | string | No | GLS contact ID (overrides config) | - ---- - -## `GLS_ALLOWED_SERVICES_RESPONSE_DATA` - -Response from the `getAllowedServices` function. - -| Field | Type | Description | -|---------------------------------|--------|------------------------------------------------------| -| `AllowedServices[]` | array | List of services or products available for the route | -| `AllowedServices[].ServiceName` | string | Name of an available service | -| `AllowedServices[].ProductName` | string | Name of an available product | - -Each element contains either `ServiceName` or `ProductName`, not both. - ---- - -## `GLS_END_OF_DAY_REQUEST_DATA` - -Input for the `getEndOfDayReport` function. - -| Field | Type | Required | Description | -|--------|-----------------|----------|-----------------------------------------------------------------| -| `date` | ISO date string | **Yes** | The date for which to retrieve the report (e.g. `"2025-01-15"`) | - ---- - -## `GLS_END_OF_DAY_RESPONSE_DATA` - -Response from the `getEndOfDayReport` function. - -| Field | Type | Description | -|-------------------------------------------------|---------------------------|----------------------------------| -| `Shipments[].ShippingDate` | ISO date | Date the shipment was dispatched | -| `Shipments[].Product` | `"PARCEL"` \| `"EXPRESS"` | Product type | -| `Shipments[].ConsigneeSchema.AddressSchema` | GLS_ADDRESS | Recipient address | -| `Shipments[].ShipperSchema.ContactID` | string | GLS contact ID of shipper | -| `Shipments[].ShipperSchema.AlternativeShipperAddress` | GLS_ADDRESS | Alternative shipper address | -| `Shipments[].ShipmentUnit[].TrackID` | string | Tracking ID | -| `Shipments[].ShipmentUnit[].Weight` | string | Parcel weight | -| `Shipments[].ShipmentUnit[].ParcelNumber` | string | GLS parcel number | - ---- - -## `GLS_UPDATE_PARCEL_WEIGHT_REQUEST_DATA` - -Input for the `updateParcelWeight` function. Provide at least one identifier (`TrackID`, `ParcelNumber`, -`ShipmentReference`, `ShipmentUnitReference`, or `PartnerParcelNumber`). - -| Field | Type | Required | Constraints | Description | -|-------------------------|--------|----------|------------------|----------------------------| -| `TrackID` | string | No | max 8 | GLS tracking ID | -| `ParcelNumber` | number | No | max 999999999999 | GLS parcel number | -| `ShipmentReference` | string | No | max 40 | Your shipment reference | -| `ShipmentUnitReference` | string | No | max 40 | Your parcel unit reference | -| `PartnerParcelNumber` | string | No | max 50 | Partner parcel number | -| `Weight` | number | **Yes** | min 0.10 | New weight in kilograms | - ---- - -## `GLS_UPDATE_PARCEL_WEIGHT_RESPONSE_DATA` - -Response from the `updateParcelWeight` function. - -| Field | Type | Description | -|-----------------|--------|--------------------------------| -| `UpdatedWeight` | string | Confirmed updated weight value | - ---- - -## `GLS_REPRINT_PARCEL_REQUEST_DATA` - -Input for the `reprintParcel` function. Provide at least one identifier. - -| Field | Type | Required | Constraints | Description | -|--------------------------------------------|-----------------|----------|----------------------------------|---------------------------------| -| `TrackID` | string | No | max 8 | GLS tracking ID | -| `ParcelNumber` | number | No | max 999999999999 | GLS parcel number | -| `ShipmentReference` | string | No | max 40 | Your shipment reference | -| `ShipmentUnitReference` | string | No | max 40 | Your parcel unit reference | -| `PartnerParcelNumber` | string | No | max 50 | Partner parcel number | -| `CreationDate` | ISO date string | **Yes** | — | Original shipment creation date | -| `PrintingOptions.ReturnLabels.TemplateSet` | enum | **Yes** | `NONE`, `ZPL_200`, `ZPL_300` | Label template | -| `PrintingOptions.ReturnLabels.LabelFormat` | enum | **Yes** | `PDF`, `ZEBRA`, `PNG`, `PNG_200` | Output format | - ---- - -## `GLS_REPRINT_PARCEL_RESPONSE_DATA` - -Response from the `reprintParcel` function. Same structure as `GLS_CREATE_PARCELS_RESPONSE` without the -`ShipmentReference` and `GDPR` fields. - -| Field | Type | Description | -|------------------------------------------------------|----------|----------------------------------| -| `CreatedShipment.ParcelData[].TrackID` | string | Tracking ID | -| `CreatedShipment.ParcelData[].ShipmentUnitReference` | string[] | Unit references | -| `CreatedShipment.ParcelData[].ParcelNumber` | string | Parcel number | -| `CreatedShipment.ParcelData[].Barcodes` | object | Barcode data | -| `CreatedShipment.ParcelData[].RoutingInfo` | object | Routing details | -| `CreatedShipment.PrintData[].Data` | string | Base64-encoded label | -| `CreatedShipment.PrintData[].LabelFormat` | enum | `PDF`, `ZEBRA`, `PNG`, `PNG_200` | -| `CreatedShipment.CustomerID` | string | GLS customer identifier | -| `CreatedShipment.PickupLocation` | string | Depot pickup location | -| `CreatedShipment.GDPR` | string[] | GDPR references | - ---- - -## `GLS_VALIDATE_SHIPMENT_REQUEST_DATA` - -Input for the `validateShipment` function. - -| Field | Type | Required | Description | -|------------|--------------|----------|-----------------------------------| -| `Shipment` | GLS_SHIPMENT | **Yes** | The complete shipment to validate | - ---- - -## `GLS_VALIDATE_SHIPMENT_RESPONSE_DATA` - -Response from the `validateShipment` function. - -| Field | Type | Description | -|----------------------------------------|----------|--------------------------------------------------| -| `success` | boolean | Whether the shipment passed all validation rules | -| `validationResult.Issues[]` | array | List of validation issues (empty if valid) | -| `validationResult.Issues[].Rule` | string | Name of the failed validation rule | -| `validationResult.Issues[].Location` | string | Path in the data where the issue was found | -| `validationResult.Issues[].Parameters` | string[] | Additional details about the issue | - ---- - -## Type dependency diagram - -``` -GLS_SHIPMENT_WITHOUT_SERVICES - ├── ConsigneeSchema: GLS_CONSIGNEE - │ └── AddressSchema: GLS_ADDRESS - ├── ShipperSchema: GLS_SHIPPER - │ ├── AddressSchema: GLS_ADDRESS - │ └── AlternativeShipperAddress: GLS_ADDRESS - └── ShipmentUnit[]: GLS_SHIPMENT_UNIT - └── Service: GLS_UNIT_SERVICE - -GLS_PRINTING_OPTIONS - └── ReturnLabels: { TemplateSet, LabelFormat } - -GLS_CUSTOM_CONTENT - └── { CustomerLogo, BarcodeContentType, Barcode, BarcodeType, HideShipperAddress } - -GLS_RETURN_OPTIONS - └── { ReturnPrintData, ReturnRoutingInfo } - -─── Shipment function ────────────────────────────────────────────── -[GLS_SHIPMENT_WITHOUT_SERVICES + GLS_PRINTING_OPTIONS + ...] → GLS_CREATE_PARCELS_RESPONSE -``` diff --git a/docs/Actions/GLS/types.mdx b/docs/Actions/GLS/types.mdx new file mode 100644 index 0000000..7110669 --- /dev/null +++ b/docs/Actions/GLS/types.mdx @@ -0,0 +1,603 @@ +--- +title: Datatypes +description: All data types registered by the GLS Action — field references and descriptions. +--- + +# 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. + +--- + +# GLS_VALIDATE_SHIPMENT_REQUEST_DATA + + + + +# GLS_VALIDATE_SHIPMENT_RESPONSE_DATA + + + + +# GLS_UPDATE_PARCEL_WEIGHT_REQUEST_DATA + + + + +# GLS_UPDATE_PARCEL_WEIGHT_RESPONSE_DATA + + + + +# GLS_UNIT_SERVICE (array) + + + + +# GLS_SHIPPER + + + + +# GLS_SHIPMENT_UNIT (array) + + + + +# GLS_SHIPMENT + + + + +# GLS_SHIPMENT_WITHOUT_SERVICES + + + + +# GLS_RETURN_OPTIONS + + + + +# GLS_REPRINT_PARCEL_REQUEST_DATA + + + + +# GLS_REPRINT_PARCEL_RESPONSE_DATA + + + + +# GLS_PRINTING_OPTIONS + + + + +# GLS_END_OF_DAY_REQUEST_DATA + + + + +# GLS_END_OF_DAY_RESPONSE_DATA + + + + +# GLS_CUSTOM_CONTENT + + + + +# GLS_CREATE_PARCELS_RESPONSE + + + + +# GLS_CONSIGNEE + + + + +# GLS_CANCEL_SHIPMENT_REQUEST_DATA + + + + +# GLS_CANCEL_SHIPMENT_RESPONSE_DATA + + + + +# GLS_ALLOWED_SERVICES_REQUEST_DATA + + + + +# GLS_ALLOWED_SERVICES_RESPONSE_DATA + + + + +# GLS_ADDRESS + + + + diff --git a/package-lock.json b/package-lock.json index f45fe06..b5fc11f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11,7 +11,7 @@ "actions/*" ], "dependencies": { - "@code0-tech/hercules": "file:code0-tech-hercules-0.0.0.tgz", + "@code0-tech/hercules": "^0.0.2", "axios": "^1.13.6", "vite": "^7.3.1", "zod": "^4.3.6", @@ -41,12 +41,12 @@ "link": true }, "node_modules/@code0-tech/hercules": { - "version": "0.0.0", - "resolved": "file:code0-tech-hercules-0.0.0.tgz", - "integrity": "sha512-MwoauVdEnfA7IvODjPt2aPbQe8m0xmFAq+smn/sIId/yeJ1ldmoJjhtDFeXpYgS6fLZQ09lgpXrTYmZAiyRPsQ==", + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/@code0-tech/hercules/-/hercules-0.0.2.tgz", + "integrity": "sha512-oG0N8zRNX8WJmYORhbNnAj75HXi6pzL+xclO3vOxHQiOBjb4hjqnRYIBtCTuR9xAJSXeOEqPu5rgK2hHKTsdzA==", "license": "ISC", "dependencies": { - "@code0-tech/tucana": "file:code0-tech-tucana-0.0.0.tgz", + "@code0-tech/tucana": "^0.0.65", "@grpc/grpc-js": "^1.14.3", "@protobuf-ts/grpc-backend": "^2.11.1", "@protobuf-ts/grpc-transport": "^2.11.1", @@ -54,10 +54,10 @@ "@protobuf-ts/runtime-rpc": "^2.11.1" } }, - "node_modules/@code0-tech/hercules/node_modules/@code0-tech/tucana": { - "version": "0.0.0", - "resolved": "file:code0-tech-tucana-0.0.0.tgz", - "integrity": "sha512-ZXpWELHdEYyeJaGue9Lq2t0sqnR4F77fxwsAaim0Q7gkilsCCzIFYPy4t3cRhfhKtw3iSknDOGrtFqvAaH6D5w==", + "node_modules/@code0-tech/tucana": { + "version": "0.0.65", + "resolved": "https://registry.npmjs.org/@code0-tech/tucana/-/tucana-0.0.65.tgz", + "integrity": "sha512-XTNAZ+iqTEf1yLU0uqNc2+ICg6tRF0w41C6da9DePoV4qDa2aRmZwA4jJyr/1i+hohZVKRrhkY7Qaf/blsyx0g==", "license": "Apache-2.0" }, "node_modules/@esbuild/aix-ppc64": { diff --git a/package.json b/package.json index 03cbe81..bed8ff4 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,7 @@ "packageManager": "npm@11.12.1", "scripts": { "build": "npm run build --workspaces --if-present", + "docs:generate": "npm run docs:generate --workspaces --if-present", "start": "turbo run start", "test": "vitest run", "test:watch": "vitest", @@ -25,7 +26,7 @@ "vitest": "^4.0.0" }, "dependencies": { - "@code0-tech/hercules": "file:code0-tech-hercules-0.0.0.tgz", + "@code0-tech/hercules": "^0.0.2", "axios": "^1.13.6", "vite": "^7.3.1", "zod": "^4.3.6", diff --git a/tsconfig.base.json b/tsconfig.base.json index fbfad07..8a0c8f5 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -3,8 +3,8 @@ "esModuleInterop": true, "module": "es2022", "moduleResolution": "bundler", - "target": "es2020", - "lib": ["es2020", "dom"], + "target": "es2021", + "lib": ["es2022", "es2021", "dom"], "strict": false, "skipLibCheck": true, "types": ["vite/client"] From 0e6d193c63c71748f93b2a0ee39726ca2badb22b Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Sun, 29 Mar 2026 21:49:58 +0200 Subject: [PATCH 02/17] Fix linter --- actions/gls-action/scripts/generateTypes.ts | 10 +++++++--- actions/gls-action/src/index.ts | 1 + 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/actions/gls-action/scripts/generateTypes.ts b/actions/gls-action/scripts/generateTypes.ts index aea98d1..d1c6422 100644 --- a/actions/gls-action/scripts/generateTypes.ts +++ b/actions/gls-action/scripts/generateTypes.ts @@ -15,10 +15,10 @@ const state = { async function run() { await loadAllDefinitions({ - onError: handler => { + onError: () => { }, - connect: options => Promise.resolve([]), - dispatchEvent: (event, payload) => Promise.resolve(), + connect: () => Promise.resolve([]), + dispatchEvent: () => Promise.resolve(), getProjectActionConfigurations: () => [], config: { authToken: "", @@ -49,6 +49,10 @@ async function run() { return Promise.resolve() }, registerFlowTypes: (...flowTypes) => { + state.flowTypes = [ + ...state.flowTypes, + ...flowTypes + ] return Promise.resolve() } diff --git a/actions/gls-action/src/index.ts b/actions/gls-action/src/index.ts index f7bae4b..ad330bf 100644 --- a/actions/gls-action/src/index.ts +++ b/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) From c86f9d0544519ec39b7c5636fef369405152dcef Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Sun, 29 Mar 2026 21:53:06 +0200 Subject: [PATCH 03/17] Fix typo --- README.md | 2 +- docs/Actions/GLS/configs.md | 2 +- docs/Actions/GLS/functions.md | 12 ++++++------ docs/Actions/GLS/overview.md | 2 +- docs/index.mdx | 2 +- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index d17526d..4cf5dca 100644 --- a/README.md +++ b/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) diff --git a/docs/Actions/GLS/configs.md b/docs/Actions/GLS/configs.md index 20d3de5..fa374e1 100644 --- a/docs/Actions/GLS/configs.md +++ b/docs/Actions/GLS/configs.md @@ -107,4 +107,4 @@ The value must be a valid `GLS_SHIPPER` object: } ``` -See [Types — GLS_SHIPPER](types.md#GLS_SHIPPER) for the full field reference. +See [Types — GLS_SHIPPER](types.mdx#GLS_SHIPPER) for the full field reference. diff --git a/docs/Actions/GLS/functions.md b/docs/Actions/GLS/functions.md index 7633a68..c5ffdde 100644 --- a/docs/Actions/GLS/functions.md +++ b/docs/Actions/GLS/functions.md @@ -56,7 +56,7 @@ createAddress( | `MobilePhonenumber` | string (min 4, max 35) | No | Mobile phone number | | `eMail` | string (max 80) | No | Email address | -**Returns:** [`GLS_ADDRESS`](types.md#GLS_ADDRESS) +**Returns:** [`GLS_ADDRESS`](types.mdx#GLS_ADDRESS) --- @@ -83,7 +83,7 @@ createConsignee( | `AddressSchema` | GLS_ADDRESS | **Yes** | The delivery address for this consignee | | `Category` | `"BUSINESS"` \| `"PRIVATE"` | **Yes** | Whether the consignee is a business or private recipient | -**Returns:** [`GLS_CONSIGNEE`](types.md#GLS_CONSIGNEE) +**Returns:** [`GLS_CONSIGNEE`](types.mdx#GLS_CONSIGNEE) --- @@ -114,7 +114,7 @@ createShipmentUnit( | `note2` | string (max 50) | No | Additional note printed on the label (line 2) | | `shipmentUnitService` | GLS_UNIT_SERVICE | No | Unit-level services (Cash, AddonLiability, HazardousGoods, etc.) | -**Returns:** [`GLS_SHIPMENT_UNIT`](types.md#GLS_SHIPMENT_UNIT) +**Returns:** [`GLS_SHIPMENT_UNIT`](types.mdx#GLS_SHIPMENT_UNIT-array) --- @@ -140,7 +140,7 @@ createPrintingOptions(returnLabels: RETURN_LABELS): GLS_PRINTING_OPTIONS | `TemplateSet` | `NONE`, `D_200`, `PF_4_I`, `ZPL_200`, `ZPL_300`, ... | Label template set | | `LabelFormat` | `PDF`, `ZEBRA`, `INTERMEC`, `DATAMAX`, `TOSHIBA`, `PNG` | Output format | -**Returns:** [`GLS_PRINTING_OPTIONS`](types.md#GLS_PRINTING_OPTIONS) +**Returns:** [`GLS_PRINTING_OPTIONS`](types.mdx#GLS_PRINTING_OPTIONS) --- @@ -169,7 +169,7 @@ createCustomContent( | `barcodeType` | `"EAN_128"` \| `"CODE_39"` | No | Barcode symbology | | `barcode` | string | No | Custom barcode value | -**Returns:** [`GLS_CUSTOM_CONTENT`](types.md#GLS_CUSTOM_CONTENT) +**Returns:** [`GLS_CUSTOM_CONTENT`](types.mdx#GLS_CUSTOM_CONTENT) --- @@ -536,7 +536,7 @@ validateShipment └── validationResult.Issues[] ``` -See [Types — GLS_VALIDATE_SHIPMENT_REQUEST_DATA](types.md#GLS_VALIDATE_SHIPMENT_REQUEST_DATA) for the input format. +See [Types — GLS_VALIDATE_SHIPMENT_REQUEST_DATA](types.mdx#GLS_VALIDATE_SHIPMENT_REQUEST_DATA) for the input format. --- diff --git a/docs/Actions/GLS/overview.md b/docs/Actions/GLS/overview.md index 3913cc9..61f2350 100644 --- a/docs/Actions/GLS/overview.md +++ b/docs/Actions/GLS/overview.md @@ -91,7 +91,7 @@ GLS_CREATE_PARCELS_RESPONSE ← tracking IDs, barcode data, print data, routing - [Quick Start](quick-start.md) — Create your first shipment in a few steps - [Configuration](configs.md) — Full list of configuration options and how to get credentials - [Functions](functions.md) — All available functions with parameter details -- [Types](types.md) — All data types used in the GLS Action +- [Types](types.mdx) — All data types used in the GLS Action - [Events](events.md) — Events emitted by the GLS Action - [Common Use Cases](use-cases.md) — Example flows for real-world scenarios - [Troubleshooting](troubleshooting.md) — FAQ and community support diff --git a/docs/index.mdx b/docs/index.mdx index 272254b..31e854a 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -37,7 +37,7 @@ Before using any action from Centaurus, make sure you have: - [GLS Action Overview](Actions/GLS/overview.md) — Get started with the GLS shipping integration - [GLS Configuration](Actions/GLS/configs.md) — API keys and configuration options - [GLS Functions](Actions/GLS/functions.md) — All available functions and their parameters -- [GLS Types](Actions/GLS/types.md) — Data types used across the GLS action +- [GLS Types](Actions/GLS/types.mdx) — Data types used across the GLS action - [GLS Events](Actions/GLS/events.md) — Events emitted by the GLS action - [Common Use Cases](Actions/GLS/use-cases.md) — Example workflows using the GLS action - [Troubleshooting](Actions/GLS/troubleshooting.md) — FAQ and community support \ No newline at end of file From 51a4902a531ff30ca20212c7824a6945d2656885 Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Mon, 30 Mar 2026 22:48:42 +0200 Subject: [PATCH 04/17] New method of generative types??? --- actions/gls-action/package.json | 3 + actions/gls-action/scripts/generateTypes.ts | 162 +- actions/gls-action/src/types/glsAddress.ts | 44 +- .../gls-action/src/types/glsUnitService.ts | 2 +- docs/Actions/GLS/functions.md | 2 +- docs/Actions/GLS/types.mdx | 1965 ++++++++++++----- package-lock.json | 41 +- tsconfig.base.json | 2 +- 8 files changed, 1580 insertions(+), 641 deletions(-) diff --git a/actions/gls-action/package.json b/actions/gls-action/package.json index 106637b..5768b95 100644 --- a/actions/gls-action/package.json +++ b/actions/gls-action/package.json @@ -11,5 +11,8 @@ "test": "vitest run", "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" } } diff --git a/actions/gls-action/scripts/generateTypes.ts b/actions/gls-action/scripts/generateTypes.ts index d1c6422..b307b8e 100644 --- a/actions/gls-action/scripts/generateTypes.ts +++ b/actions/gls-action/scripts/generateTypes.ts @@ -3,6 +3,7 @@ import { HerculesActionConfigurationDefinition, HerculesDataType, HerculesFlowType, HerculesRegisterFunctionParameter, } from "@code0-tech/hercules"; +import {Project, SymbolFlags, Type} from "ts-morph"; const state = { @@ -60,10 +61,11 @@ async function run() { } run().then(async () => { - let typeContent = `--- + 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 @@ -71,66 +73,150 @@ The GLS Action registers the following data types with the Hercules platform. Th 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, "") - .replace(/\/\*\*/g, "/**\n") - .replace(/\*\//g, "\n**/") - .replace( - /(\w+)(\?)?:\s*(GLS_\w+);/g, - (match, name, optionalMark, gls) => { - if (optionalMark) { - return `/** - Optional. - @fumadocsHref #type-table-temp.ts-${gls} -**/ -${name}: ${gls}`; + + + function breakDown( + typeName: string, + code: string + ): Record { + const map: Record = {}; + + 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; } - return `/** - @fumadocsHref #type-table-temp.ts-${gls} -**/ -${name}: ${gls}`; - } - ); + let typeText: string; - let array = false - if (value.type.endsWith("[];")) { - value.type = value.type.slice(0, -3) + ";" - array = true - } + if (propType.getText().startsWith("{")) { + const newName = `${currentName}$${name}`; - typeContent += ` -# ${value.identifier}${array ? " (array)" : ""} - - + // recurse first + const nestedType = buildType(propType, newName); -` - }) - typeContent = typeContent.replace(" | undefined", "") + 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` : ""; - console.log(typeContent) -}) + 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 = `` + console.log(`# ${key}`) + console.log(table) + } + // console.log(` +// # ${value.identifier} ${array ? "[]" : ""} +// `) +// console.log(table) + }) +}) \ No newline at end of file diff --git a/actions/gls-action/src/types/glsAddress.ts b/actions/gls-action/src/types/glsAddress.ts index 4d76bc6..05f5a86 100644 --- a/actions/gls-action/src/types/glsAddress.ts +++ b/actions/gls-action/src/types/glsAddress.ts @@ -4,60 +4,42 @@ import {singleZodSchemaToTypescriptDef} from "../helpers"; export const AddressSchema = z.object({ Name1: z.string().max(40).describe(` - Primary name line (person or company). - Max 40 characters. + @description Primary name line (person or company). Max 40 characters. `), Name2: z.string().max(40).optional().describe(` - Optional second name line (e.g., department or additional identifier). - Max 40 characters. + @description Optional second name line (e.g., department or additional identifier). Max 40 characters. `), Name3: z.string().max(40).optional().describe(` - Optional third name line for extended address details. - Max 40 characters. + @description Optional third name line for extended address details. Max 40 characters. `), CountryCode: z.string().max(2).describe(` - Two-letter ISO country code (e.g., DE, US). + @description Two-letter ISO country code (e.g., DE, US). `), Province: z.string().max(40).optional().describe(` - State, province, or region. - Optional field. - Max 40 characters. + @description State, province, or region. Optional field. Max 40 characters. `), City: z.string().max(40).describe(` - City or locality name. - Max 40 characters. + @description City or locality name. Max 40 characters. `), Street: z.string().min(4).describe(` - Street name. - Minimum 4 characters required. + @description Street name. Minimum 4 characters required. `), StreetNumber: z.string().max(40).optional().describe(` - House or building number. - Optional field. - Max 40 characters. + @description House or building number. Optional field. Max 40 characters. `), ContactPerson: z.string().max(40).min(6).optional().describe(` - Full name of a contact person. - Optional field. - Must be between 6 and 40 characters. + @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(` - Landline phone number. - Optional field. - Must be between 4 and 35 characters. + @description Landline phone number. Optional field. Must be between 4 and 35 characters. `), MobilePhonenumber: z.string().max(35).min(4).optional().describe(` - Mobile phone number. - Optional field. - Must be between 4 and 35 characters. + @description Mobile phone number. Optional field. Must be between 4 and 35 characters. `), eMail: z.string().max(80).optional().describe(` - Email address. - Optional field. - Max 80 characters. + @description Email address. Optional field. Max 80 characters. `), ZIPCode: z.string().max(10).describe(` - Postal or ZIP code. - Max 10 characters. + @description Postal or ZIP code. Max 10 characters. `), }) export type AddressSchema = z.infer diff --git a/actions/gls-action/src/types/glsUnitService.ts b/actions/gls-action/src/types/glsUnitService.ts index 8976cde..050fe26 100644 --- a/actions/gls-action/src/types/glsUnitService.ts +++ b/actions/gls-action/src/types/glsUnitService.ts @@ -5,7 +5,7 @@ import {ActionSdk} from "@code0-tech/hercules"; export const UnitServiceSchema = z.array(z.object({ Cash: z.object({ - Reason: z.string().max(160), + Reason: z.string().max(160).describe("@description Test"), Amount: z.number().min(1), Currency: z.string().max(3).min(3) }).optional(), diff --git a/docs/Actions/GLS/functions.md b/docs/Actions/GLS/functions.md index c5ffdde..fdb68ee 100644 --- a/docs/Actions/GLS/functions.md +++ b/docs/Actions/GLS/functions.md @@ -114,7 +114,7 @@ createShipmentUnit( | `note2` | string (max 50) | No | Additional note printed on the label (line 2) | | `shipmentUnitService` | GLS_UNIT_SERVICE | No | Unit-level services (Cash, AddonLiability, HazardousGoods, etc.) | -**Returns:** [`GLS_SHIPMENT_UNIT`](types.mdx#GLS_SHIPMENT_UNIT-array) +**Returns:** [`GLS_SHIPMENT_UNIT`](types.mdx#gls_shipment_unit) --- diff --git a/docs/Actions/GLS/types.mdx b/docs/Actions/GLS/types.mdx index 7110669..04ac827 100644 --- a/docs/Actions/GLS/types.mdx +++ b/docs/Actions/GLS/types.mdx @@ -2,6 +2,7 @@ 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 @@ -11,593 +12,1427 @@ of the GLS functions and can be referenced in your flows. --- # GLS_VALIDATE_SHIPMENT_REQUEST_DATA - - - - + # GLS_VALIDATE_SHIPMENT_RESPONSE_DATA - - - - + +# GLS_VALIDATE_SHIPMENT_RESPONSE_DATA$validationResult + +# GLS_VALIDATE_SHIPMENT_RESPONSE_DATA$validationResult$Issues + # GLS_UPDATE_PARCEL_WEIGHT_REQUEST_DATA - - - - + # GLS_UPDATE_PARCEL_WEIGHT_RESPONSE_DATA - - - - -# GLS_UNIT_SERVICE (array) - - - - + +# GLS_UNIT_SERVICE + +# GLS_UNIT_SERVICE$LimitedQuantities + +# GLS_UNIT_SERVICE$ExWorks + +# GLS_UNIT_SERVICE$HazardousGoods + +# GLS_UNIT_SERVICE$HazardousGoods$HarzardousGood + +# GLS_UNIT_SERVICE$AddonLiability + +# GLS_UNIT_SERVICE$Cash + # GLS_SHIPPER - - - - -# GLS_SHIPMENT_UNIT (array) - - +# GLS_SHIPMENT_UNIT + +# GLS_SHIPMENT_UNIT$Service + +# GLS_SHIPMENT_UNIT$Service$LimitedQuantities + +# GLS_SHIPMENT_UNIT$Service$ExWorks + +# GLS_SHIPMENT_UNIT$Service$HazardousGoods + - - + description: 'No description set', + deprecated: false, + required: true, +typeDescriptionLink: '#gls_shipment_unitservicehazardousgoodsharzardousgood', + type: 'GLS_SHIPMENT_UNIT$Service$HazardousGoods$HarzardousGood[]', + }, + }} +/> +# GLS_SHIPMENT_UNIT$Service$HazardousGoods$HarzardousGood + +# GLS_SHIPMENT_UNIT$Service$AddonLiability + +# GLS_SHIPMENT_UNIT$Service$Cash + # GLS_SHIPMENT - - - - + +# GLS_SHIPMENT$Return + # GLS_SHIPMENT_WITHOUT_SERVICES - - - - + +# GLS_SHIPMENT_WITHOUT_SERVICES$Return + # GLS_RETURN_OPTIONS - - - - + # GLS_REPRINT_PARCEL_REQUEST_DATA - - - - + +# GLS_REPRINT_PARCEL_REQUEST_DATA$PrintingOptions + +# GLS_REPRINT_PARCEL_REQUEST_DATA$PrintingOptions$ReturnLabels + # GLS_REPRINT_PARCEL_RESPONSE_DATA - - +# GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment + +# GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$PrintData + +# GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData + - - + description: 'No description set', + deprecated: false, + required: true, +typeDescriptionLink: '#gls_reprint_parcel_response_datacreatedshipmentparceldataroutinginfo', + type: 'GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData$RoutingInfo', + }, + }} +/> +# GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData$RoutingInfo + +# GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData$Barcodes + # GLS_PRINTING_OPTIONS - - - - + +# GLS_PRINTING_OPTIONS$DefinePrinter + +# GLS_PRINTING_OPTIONS$ReturnLabels + # GLS_END_OF_DAY_REQUEST_DATA - - - - + # GLS_END_OF_DAY_RESPONSE_DATA - - - - + +# GLS_END_OF_DAY_RESPONSE_DATA$Shipments + +# GLS_END_OF_DAY_RESPONSE_DATA$Shipments$ShipmentUnit + +# GLS_END_OF_DAY_RESPONSE_DATA$Shipments$Shipper + +# GLS_END_OF_DAY_RESPONSE_DATA$Shipments$Consignee + # GLS_CUSTOM_CONTENT - - - - + # GLS_CREATE_PARCELS_RESPONSE - - +# GLS_CREATE_PARCELS_RESPONSE$CreatedShipment + +# GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$PrintData + +# GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData + - - + description: 'No description set', + deprecated: false, + required: true, +typeDescriptionLink: '#gls_create_parcels_responsecreatedshipmentparceldataroutinginfo', + type: 'GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData$RoutingInfo', + }, + }} +/> +# GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData$RoutingInfo + +# GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData$Barcodes + # GLS_CONSIGNEE - - - - + # GLS_CANCEL_SHIPMENT_REQUEST_DATA - - - - + # GLS_CANCEL_SHIPMENT_RESPONSE_DATA - - - - + # GLS_ALLOWED_SERVICES_REQUEST_DATA - - - - + +# GLS_ALLOWED_SERVICES_REQUEST_DATA$Destination + +# GLS_ALLOWED_SERVICES_REQUEST_DATA$Source + # GLS_ALLOWED_SERVICES_RESPONSE_DATA - - - - + +# GLS_ALLOWED_SERVICES_RESPONSE_DATA$AllowedServices + # GLS_ADDRESS - - - - + diff --git a/package-lock.json b/package-lock.json index b5fc11f..765c3b4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -29,7 +29,10 @@ }, "actions/gls-action": { "name": "@code0-tech/gls-action", - "version": "0.0.0" + "version": "0.0.0", + "dependencies": { + "ts-morph": "^27.0.2" + } }, "actions/notion-action": { "name": "@code0-tech/notion-action", @@ -1141,6 +1144,17 @@ "dev": true, "license": "MIT" }, + "node_modules/@ts-morph/common": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@ts-morph/common/-/common-0.28.1.tgz", + "integrity": "sha512-W74iWf7ILp1ZKNYXY5qbddNaml7e9Sedv5lvU1V8lftlitkc9Pq1A+jlH23ltDgWYeZFFEqGCD1Ies9hqu3O+g==", + "license": "MIT", + "dependencies": { + "minimatch": "^10.0.1", + "path-browserify": "^1.0.1", + "tinyglobby": "^0.2.14" + } + }, "node_modules/@turbo/darwin-64": { "version": "2.8.21", "resolved": "https://registry.npmjs.org/@turbo/darwin-64/-/darwin-64-2.8.21.tgz", @@ -1708,7 +1722,6 @@ "version": "4.0.4", "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz", "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==", - "dev": true, "license": "MIT", "engines": { "node": "18 || 20 || >=22" @@ -1718,7 +1731,6 @@ "version": "5.0.5", "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz", "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==", - "dev": true, "license": "MIT", "dependencies": { "balanced-match": "^4.0.2" @@ -1764,6 +1776,12 @@ "node": ">=12" } }, + "node_modules/code-block-writer": { + "version": "13.0.3", + "resolved": "https://registry.npmjs.org/code-block-writer/-/code-block-writer-13.0.3.tgz", + "integrity": "sha512-Oofo0pq3IKnsFtuHqSF7TqBfr71aeyZDVJ0HpmqB7FBM2qEigL0iPONSCZSO9pE9dZTAxANe5XHG9Uy0YMv8cg==", + "license": "MIT" + }, "node_modules/color-convert": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", @@ -2597,7 +2615,6 @@ "version": "10.2.4", "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.4.tgz", "integrity": "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg==", - "dev": true, "license": "BlueOak-1.0.0", "dependencies": { "brace-expansion": "^5.0.2" @@ -2702,6 +2719,12 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/path-browserify": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/path-browserify/-/path-browserify-1.0.1.tgz", + "integrity": "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==", + "license": "MIT" + }, "node_modules/path-exists": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", @@ -3026,6 +3049,16 @@ "typescript": ">=4.8.4" } }, + "node_modules/ts-morph": { + "version": "27.0.2", + "resolved": "https://registry.npmjs.org/ts-morph/-/ts-morph-27.0.2.tgz", + "integrity": "sha512-fhUhgeljcrdZ+9DZND1De1029PrE+cMkIP7ooqkLRTrRLTqcki2AstsyJm0vRNbTbVCNJ0idGlbBrfqc7/nA8w==", + "license": "MIT", + "dependencies": { + "@ts-morph/common": "~0.28.1", + "code-block-writer": "^13.0.3" + } + }, "node_modules/turbo": { "version": "2.8.21", "resolved": "https://registry.npmjs.org/turbo/-/turbo-2.8.21.tgz", diff --git a/tsconfig.base.json b/tsconfig.base.json index 8a0c8f5..3363612 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -7,7 +7,7 @@ "lib": ["es2022", "es2021", "dom"], "strict": false, "skipLibCheck": true, - "types": ["vite/client"] + "types": ["vite/client"], }, "include": ["src/**/*"], "exclude": ["node_modules", "dist", "***/test/**", "**/*.test.ts"] From 531b63204d94b64ac849080618308846514164a8 Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Wed, 1 Apr 2026 19:53:09 +0200 Subject: [PATCH 05/17] Add global documentation handling and default value for Product field --- actions/gls-action/scripts/generateTypes.ts | 14 ++- actions/gls-action/src/types/glsShipment.ts | 2 +- docs/Actions/GLS/types.mdx | 124 ++++++++++++++++++++ 3 files changed, 134 insertions(+), 6 deletions(-) diff --git a/actions/gls-action/scripts/generateTypes.ts b/actions/gls-action/scripts/generateTypes.ts index b307b8e..004214f 100644 --- a/actions/gls-action/scripts/generateTypes.ts +++ b/actions/gls-action/scripts/generateTypes.ts @@ -78,7 +78,6 @@ of the GLS functions and can be referenced in your flows. value.type = `export type ${value.identifier} = ${value.type}` .replace(/ \| undefined/g, "") - function breakDown( typeName: string, code: string @@ -172,6 +171,7 @@ of the GLS functions and can be referenced in your flows. if (array) { type = type.getArrayElementTypeOrThrow() } + let globalDocumentation: string type.getProperties().forEach(property => { const name = property.getName(); @@ -189,9 +189,15 @@ of the GLS functions and can be referenced in your flows. property.getJsDocTags().forEach(info => { info.getText().forEach(part => { + if (info.getName() === "global") { + globalDocumentation = (globalDocumentation || "") + "\n" + part.text.trim() + return + } docs[info.getName()] = part.text.trim() }) + }) + if (currTypeText.startsWith("GLS_")) { docs.link = currTypeText.toLowerCase() .replace(/-/g, "_") @@ -211,12 +217,10 @@ of the GLS functions and can be referenced in your flows. const table = `` console.log(`# ${key}`) + console.log(globalDocumentation || "\nNo documentation provided for this type.") + console.log() console.log(table) } - // console.log(` -// # ${value.identifier} ${array ? "[]" : ""} -// `) -// console.log(table) }) }) \ No newline at end of file diff --git a/actions/gls-action/src/types/glsShipment.ts b/actions/gls-action/src/types/glsShipment.ts index 2bae894..e245db9 100644 --- a/actions/gls-action/src/types/glsShipment.ts +++ b/actions/gls-action/src/types/glsShipment.ts @@ -12,7 +12,7 @@ export const ShipmentSchema = z.object({ ShipmentDate: z.date().optional(), IncotermCode: z.int().max(99).optional(), Identifier: z.string().max(40).optional(), - Product: z.enum(["PARCEL", "EXPRESS"]), + Product: z.enum(["PARCEL", "EXPRESS"]).default("PARCEL"), ExpressAltDeliveryAllowed: z.boolean().optional(), Consignee: ConsigneeSchema, Shipper: ShipperSchema.optional(), diff --git a/docs/Actions/GLS/types.mdx b/docs/Actions/GLS/types.mdx index 04ac827..c5d5e18 100644 --- a/docs/Actions/GLS/types.mdx +++ b/docs/Actions/GLS/types.mdx @@ -12,6 +12,8 @@ of the GLS functions and can be referenced in your flows. --- # GLS_VALIDATE_SHIPMENT_REQUEST_DATA +No documentation provided for this type. + # GLS_VALIDATE_SHIPMENT_RESPONSE_DATA +No documentation provided for this type. + # GLS_VALIDATE_SHIPMENT_RESPONSE_DATA$validationResult +No documentation provided for this type. + # GLS_VALIDATE_SHIPMENT_RESPONSE_DATA$validationResult$Issues +No documentation provided for this type. + # GLS_UPDATE_PARCEL_WEIGHT_REQUEST_DATA +No documentation provided for this type. + # GLS_UPDATE_PARCEL_WEIGHT_RESPONSE_DATA +No documentation provided for this type. + # GLS_UNIT_SERVICE +No documentation provided for this type. + # GLS_UNIT_SERVICE$LimitedQuantities +No documentation provided for this type. + # GLS_UNIT_SERVICE$ExWorks +No documentation provided for this type. + # GLS_UNIT_SERVICE$HazardousGoods +No documentation provided for this type. + # GLS_UNIT_SERVICE$HazardousGoods$HarzardousGood +No documentation provided for this type. + # GLS_UNIT_SERVICE$AddonLiability +No documentation provided for this type. + # GLS_UNIT_SERVICE$Cash +No documentation provided for this type. + # GLS_SHIPPER +No documentation provided for this type. + # GLS_SHIPMENT_UNIT +No documentation provided for this type. + # GLS_SHIPMENT_UNIT$Service +No documentation provided for this type. + # GLS_SHIPMENT_UNIT$Service$LimitedQuantities +No documentation provided for this type. + # GLS_SHIPMENT_UNIT$Service$ExWorks +No documentation provided for this type. + # GLS_SHIPMENT_UNIT$Service$HazardousGoods +No documentation provided for this type. + # GLS_SHIPMENT_UNIT$Service$HazardousGoods$HarzardousGood +No documentation provided for this type. + # GLS_SHIPMENT_UNIT$Service$AddonLiability +No documentation provided for this type. + # GLS_SHIPMENT_UNIT$Service$Cash +No documentation provided for this type. + # GLS_SHIPMENT +No documentation provided for this type. + # GLS_SHIPMENT$Return +No documentation provided for this type. + # GLS_SHIPMENT_WITHOUT_SERVICES +No documentation provided for this type. + # GLS_SHIPMENT_WITHOUT_SERVICES$Return +No documentation provided for this type. + # GLS_RETURN_OPTIONS +No documentation provided for this type. + # GLS_REPRINT_PARCEL_REQUEST_DATA +No documentation provided for this type. + # GLS_REPRINT_PARCEL_REQUEST_DATA$PrintingOptions +No documentation provided for this type. + # GLS_REPRINT_PARCEL_REQUEST_DATA$PrintingOptions$ReturnLabels +No documentation provided for this type. + # GLS_REPRINT_PARCEL_RESPONSE_DATA +No documentation provided for this type. + # GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment +No documentation provided for this type. + # GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$PrintData +No documentation provided for this type. + # GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData +No documentation provided for this type. + # GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData$RoutingInfo +No documentation provided for this type. + # GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData$Barcodes +No documentation provided for this type. + # GLS_PRINTING_OPTIONS +No documentation provided for this type. + # GLS_PRINTING_OPTIONS$DefinePrinter +No documentation provided for this type. + # GLS_PRINTING_OPTIONS$ReturnLabels +No documentation provided for this type. + # GLS_END_OF_DAY_REQUEST_DATA +No documentation provided for this type. + # GLS_END_OF_DAY_RESPONSE_DATA +No documentation provided for this type. + # GLS_END_OF_DAY_RESPONSE_DATA$Shipments +No documentation provided for this type. + # GLS_END_OF_DAY_RESPONSE_DATA$Shipments$ShipmentUnit +No documentation provided for this type. + # GLS_END_OF_DAY_RESPONSE_DATA$Shipments$Shipper +No documentation provided for this type. + # GLS_END_OF_DAY_RESPONSE_DATA$Shipments$Consignee +No documentation provided for this type. + # GLS_CUSTOM_CONTENT +No documentation provided for this type. + # GLS_CREATE_PARCELS_RESPONSE +No documentation provided for this type. + # GLS_CREATE_PARCELS_RESPONSE$CreatedShipment +No documentation provided for this type. + # GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$PrintData +No documentation provided for this type. + # GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData +No documentation provided for this type. + # GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData$RoutingInfo +No documentation provided for this type. + # GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData$Barcodes +No documentation provided for this type. + # GLS_CONSIGNEE +No documentation provided for this type. + # GLS_CANCEL_SHIPMENT_REQUEST_DATA +No documentation provided for this type. + # GLS_CANCEL_SHIPMENT_RESPONSE_DATA +No documentation provided for this type. + # GLS_ALLOWED_SERVICES_REQUEST_DATA +No documentation provided for this type. + # GLS_ALLOWED_SERVICES_REQUEST_DATA$Destination +No documentation provided for this type. + # GLS_ALLOWED_SERVICES_REQUEST_DATA$Source +No documentation provided for this type. + # GLS_ALLOWED_SERVICES_RESPONSE_DATA +No documentation provided for this type. + # GLS_ALLOWED_SERVICES_RESPONSE_DATA$AllowedServices +No documentation provided for this type. + # GLS_ADDRESS + +Some Global address documentation +test2 + Date: Thu, 2 Apr 2026 13:22:56 +0200 Subject: [PATCH 06/17] Update documentation generation process and enhance type definitions --- .github/workflows/test.yml | 7 + actions/gls-action/package.json | 2 +- .../{generateTypes.ts => generateDocs.ts} | 174 +- .../src/functions/cancelShipment.ts | 6 + .../src/functions/getAllowedServices.ts | 6 + .../src/functions/getEndOfDayReport.ts | 6 + .../gls-action/src/functions/reprintParcel.ts | 6 + .../services/createAddresseeOnlyShipment.ts | 9 +- .../services/createDeliveryAtWorkShipment.ts | 6 + .../createDeliveryNextWorkingDayShipment.ts | 6 + .../createDeliverySaturdayShipment.ts | 6 + .../services/createDepositShipment.ts | 6 + .../services/createExchangeShipment.ts | 6 + .../services/createFlexDeliveryShipment.ts | 6 + .../services/createGuaranteed24Shipment.ts | 6 + .../services/createIdentPinShipment.ts | 6 + .../functions/services/createIdentShipment.ts | 6 + .../services/createPickAndShipShipment.ts | 6 + .../services/createShopDeliveryShipment.ts | 10 +- .../services/createShopReturnShipment.ts | 6 + .../services/createSignatureShipment.ts | 6 + .../functions/services/createTyreShipment.ts | 6 + .../src/functions/updateParcelWeight.ts | 6 + .../src/functions/utils/createAddress.ts | 8 +- .../src/functions/utils/createConsignee.ts | 8 +- .../functions/utils/createCustomContent.ts | 6 + .../functions/utils/createPrintingOptions.ts | 8 +- .../src/functions/utils/createShipmentUnit.ts | 8 +- .../src/functions/validateShipment.ts | 12 + actions/gls-action/tsconfig.json | 2 +- actions/gls-action/vite.config.ts | 2 +- docs/Actions/GLS/functions.mdx | 2625 +++++++++++++++++ docs/Actions/GLS/types.mdx | 67 +- 33 files changed, 3028 insertions(+), 28 deletions(-) rename actions/gls-action/scripts/{generateTypes.ts => generateDocs.ts} (58%) create mode 100644 docs/Actions/GLS/functions.mdx diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d5b83cd..6532950 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -17,3 +17,10 @@ jobs: - run: npm run build - run: npm run lint - run: npm run test + - name: Validate generated documentation + run: | + npm run generate:docs + if ! git diff --quiet; then + git --no-pager diff + exit 1 + fi \ No newline at end of file diff --git a/actions/gls-action/package.json b/actions/gls-action/package.json index 5768b95..1fcf26d 100644 --- a/actions/gls-action/package.json +++ b/actions/gls-action/package.json @@ -10,7 +10,7 @@ "lint": "eslint .", "test": "vitest run", "start": "node dist/main.js", - "docs:generate": "npm run build && node dist/generateTypes.js > ../../docs/Actions/GLS/types.mdx" + "generate:docs": "npm run build && node dist/generateDocs.js" }, "dependencies": { "ts-morph": "^27.0.2" diff --git a/actions/gls-action/scripts/generateTypes.ts b/actions/gls-action/scripts/generateDocs.ts similarity index 58% rename from actions/gls-action/scripts/generateTypes.ts rename to actions/gls-action/scripts/generateDocs.ts index 004214f..03713b6 100644 --- a/actions/gls-action/scripts/generateTypes.ts +++ b/actions/gls-action/scripts/generateDocs.ts @@ -1,9 +1,11 @@ import {loadAllDefinitions} from "../src/helpers"; import { + ActionSdk, HerculesActionConfigurationDefinition, HerculesDataType, HerculesFlowType, HerculesRegisterFunctionParameter, } from "@code0-tech/hercules"; import {Project, SymbolFlags, Type} from "ts-morph"; +import {writeFileSync} from "fs" const state = { @@ -14,8 +16,8 @@ const state = { } -async function run() { - await loadAllDefinitions({ +async function run(): Promise { + const sdk = { onError: () => { }, connect: () => Promise.resolve([]), @@ -57,13 +59,19 @@ async function run() { return Promise.resolve() } - }) + }; + await loadAllDefinitions(sdk) + + return sdk } -run().then(async () => { - console.log(`--- + +function generateDatatypes(): string { + let generatedDoc = "" + + generatedDoc += `--- title: Datatypes -description: All data types registered by the GLS Action — field references and descriptions. +description: All data types registered by the GLS Action. --- import {TypeTable} from "fumadocs-ui/components/type-table"; @@ -73,7 +81,8 @@ The GLS Action registers the following data types with the Hercules platform. Th 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, "") @@ -216,11 +225,152 @@ of the GLS functions and can be referenced in your flows. const table = `` - console.log(`# ${key}`) - console.log(globalDocumentation || "\nNo documentation provided for this type.") - console.log() - console.log(table) + generatedDoc += ` +# ${key}${globalDocumentation || "\nNo documentation provided for this type."} + +${table} + ` } }) + return generatedDoc +} + +interface Translation { + code?: string; + content?: string; +} + +interface FunctionDefinition { + descriptions?: Array; + displayMessages?: Array; + identifier?: string; + names?: Array; + parameterDefinitions?: { + nodes: { + identifier: string, + descriptions: Array, + names: Array + }[] + }; +} + +async function generateFunctions(sdk: ActionSdk): Promise { + async function loadFunctions(modules: Record Promise>) { + for (const path in modules) { + + const mod: any = await modules[path](); + if (typeof mod.default === 'function') { + try { + await mod.default(sdk); + } catch (error) { + console.log(`Error registering functions from ${path}:`, error); + } + } + } + } + + let generatedDoc = `--- +title: Functions +description: All functions registered by the GLS Action. +--- + +The GLS Action exposes ${state.runtimeFunctions.length} functions grouped into three categories: + +- **Builder functions** — Construct data objects (no API call) +- **Shipment functions** — Create different types of GLS shipments (calls GLS API) +- **API functions** — Query or modify shipments (calls GLS API) + +--- +` + const functionGlobs = [ + import.meta.glob('../src/functions/utils/*.ts'), + import.meta.glob('../src/functions/services/*.ts'), + import.meta.glob('../src/functions/*.ts') + ] + for (let i = 0; i < functionGlobs.length; i++) { + const modules = functionGlobs[i] + state.runtimeFunctions = [] + await loadFunctions(modules) + + switch (i) { + case 0: { + generatedDoc += ` +## Builder functions + ` + break + } + case 1: { + generatedDoc += ` +## Shipment functions + +All shipment functions accept a common set of parameters in addition to their type-specific parameters. They call the GLS ShipIT API (\`POST /rs/shipments\`) and return a \`GLS_CREATE_PARCELS_RESPONSE\`. + +**Common parameters for all shipment functions:** + +| Parameter | Type | Required | Description | +|-------------------|-------------------------------|----------|----------------------------------------------------| +| \`shipment\` | GLS_SHIPMENT_WITHOUT_SERVICES | **Yes** | Shipment data (consignee, shipper, units, product) | +| \`printingOptions\` | GLS_PRINTING_OPTIONS | **Yes** | Label format settings | +| \`returnOptions\` | GLS_RETURN_OPTIONS | No | Whether to return print data and routing info | +| \`customContent\` | GLS_CUSTOM_CONTENT | No | Custom logo and barcode settings | + +--- + ` + break + } + default: { + generatedDoc += ` + ## API functions + ` + } + } + + state.runtimeFunctions.forEach(value => { + const definition = value.definition; + const generateDefinition: FunctionDefinition = { + descriptions: definition.description, + names: definition.name, + identifier: definition.runtimeName, + parameterDefinitions: { + nodes: definition.parameters.map(p => { + return { + names: p.name, + identifier: p.runtimeName, + descriptions: p.description + } + }) + }, + displayMessages: definition.displayMessage + } + + generatedDoc += ` +### \`${definition.runtimeName}\` + +${definition.documentation?.at(0).content || ""} + + + +--- +` + }) + } + + + return generatedDoc +} -}) \ No newline at end of file +run().then(async (sdk) => { + // writeFileSync( + // "../../docs/Actions/GLS/types.mdx", + // generateDatatypes(), + // "utf8" + // ) + + writeFileSync( + "../../docs/Actions/GLS/functions.mdx", + await generateFunctions(sdk), + "utf-8" + ) +}) diff --git a/actions/gls-action/src/functions/cancelShipment.ts b/actions/gls-action/src/functions/cancelShipment.ts index c08f9e9..50d562f 100644 --- a/actions/gls-action/src/functions/cancelShipment.ts +++ b/actions/gls-action/src/functions/cancelShipment.ts @@ -7,6 +7,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "cancelShipment", + displayMessage: [ + { + code: "en-US", + content: "Cancel shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/getAllowedServices.ts b/actions/gls-action/src/functions/getAllowedServices.ts index dad11a3..4754342 100644 --- a/actions/gls-action/src/functions/getAllowedServices.ts +++ b/actions/gls-action/src/functions/getAllowedServices.ts @@ -12,6 +12,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "getAllowedServices", + displayMessage: [ + { + code: "en-US", + content: "Get allowed services" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/getEndOfDayReport.ts b/actions/gls-action/src/functions/getEndOfDayReport.ts index 150fca0..a5dd7c6 100644 --- a/actions/gls-action/src/functions/getEndOfDayReport.ts +++ b/actions/gls-action/src/functions/getEndOfDayReport.ts @@ -8,6 +8,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "getEndOfDayReport", + displayMessage: [ + { + code: "en-US", + content: "Get end of day report" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/reprintParcel.ts b/actions/gls-action/src/functions/reprintParcel.ts index 2270586..9b19744 100644 --- a/actions/gls-action/src/functions/reprintParcel.ts +++ b/actions/gls-action/src/functions/reprintParcel.ts @@ -12,6 +12,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "reprintParcel", + displayMessage: [ + { + code: "en-US", + content: "Reprint parcel" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createAddresseeOnlyShipment.ts b/actions/gls-action/src/functions/services/createAddresseeOnlyShipment.ts index 866a3b3..c1fe032 100644 --- a/actions/gls-action/src/functions/services/createAddresseeOnlyShipment.ts +++ b/actions/gls-action/src/functions/services/createAddresseeOnlyShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createAddresseeOnlyShipment", + displayMessage: [ + { + code: "en-US", + content: "Create addressee only shipment" + } + ], name: [ { code: "en-US", @@ -44,4 +50,5 @@ export default (sdk: ActionSdk) => { } }, ) -} \ No newline at end of file +} + diff --git a/actions/gls-action/src/functions/services/createDeliveryAtWorkShipment.ts b/actions/gls-action/src/functions/services/createDeliveryAtWorkShipment.ts index 2e48ea6..b115393 100644 --- a/actions/gls-action/src/functions/services/createDeliveryAtWorkShipment.ts +++ b/actions/gls-action/src/functions/services/createDeliveryAtWorkShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createDeliveryAtWorkShipment", + displayMessage: [ + { + code: "en-US", + content: "Create delivery at work shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createDeliveryNextWorkingDayShipment.ts b/actions/gls-action/src/functions/services/createDeliveryNextWorkingDayShipment.ts index d3edcc9..9b2f35d 100644 --- a/actions/gls-action/src/functions/services/createDeliveryNextWorkingDayShipment.ts +++ b/actions/gls-action/src/functions/services/createDeliveryNextWorkingDayShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createDeliveryNextWorkingDayShipment", + displayMessage: [ + { + code: "en-US", + content: "Create delivery next working day shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createDeliverySaturdayShipment.ts b/actions/gls-action/src/functions/services/createDeliverySaturdayShipment.ts index 59ec597..b99436e 100644 --- a/actions/gls-action/src/functions/services/createDeliverySaturdayShipment.ts +++ b/actions/gls-action/src/functions/services/createDeliverySaturdayShipment.ts @@ -16,6 +16,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createDeliverySaturdayShipment", + displayMessage: [ + { + code: "en-US", + content: "Create delivery Saturday shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createDepositShipment.ts b/actions/gls-action/src/functions/services/createDepositShipment.ts index 2964d0d..99458f4 100644 --- a/actions/gls-action/src/functions/services/createDepositShipment.ts +++ b/actions/gls-action/src/functions/services/createDepositShipment.ts @@ -16,6 +16,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createDepositShipment", + displayMessage: [ + { + code: "en-US", + content: "Create deposit shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createExchangeShipment.ts b/actions/gls-action/src/functions/services/createExchangeShipment.ts index 7b99638..6915c7c 100644 --- a/actions/gls-action/src/functions/services/createExchangeShipment.ts +++ b/actions/gls-action/src/functions/services/createExchangeShipment.ts @@ -16,6 +16,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createExchangeShipment", + displayMessage: [ + { + code: "en-US", + content: "Create exchange shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createFlexDeliveryShipment.ts b/actions/gls-action/src/functions/services/createFlexDeliveryShipment.ts index 99f5c29..423f13e 100644 --- a/actions/gls-action/src/functions/services/createFlexDeliveryShipment.ts +++ b/actions/gls-action/src/functions/services/createFlexDeliveryShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createFlexDeliveryShipment", + displayMessage: [ + { + code: "en-US", + content: "Create flex delivery shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createGuaranteed24Shipment.ts b/actions/gls-action/src/functions/services/createGuaranteed24Shipment.ts index 880bad9..3d2964b 100644 --- a/actions/gls-action/src/functions/services/createGuaranteed24Shipment.ts +++ b/actions/gls-action/src/functions/services/createGuaranteed24Shipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createGuaranteed24Shipment", + displayMessage: [ + { + code: "en-US", + content: "Create guaranteed 24 shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createIdentPinShipment.ts b/actions/gls-action/src/functions/services/createIdentPinShipment.ts index 7f0a031..d733edc 100644 --- a/actions/gls-action/src/functions/services/createIdentPinShipment.ts +++ b/actions/gls-action/src/functions/services/createIdentPinShipment.ts @@ -16,6 +16,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createIdentPinShipment", + displayMessage: [ + { + code: "en-US", + content: "Create ident pin shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createIdentShipment.ts b/actions/gls-action/src/functions/services/createIdentShipment.ts index a0ea990..14f72ce 100644 --- a/actions/gls-action/src/functions/services/createIdentShipment.ts +++ b/actions/gls-action/src/functions/services/createIdentShipment.ts @@ -16,6 +16,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createIdentShipment", + displayMessage: [ + { + code: "en-US", + content: "Create ident shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createPickAndShipShipment.ts b/actions/gls-action/src/functions/services/createPickAndShipShipment.ts index f1f101d..ae79ae8 100644 --- a/actions/gls-action/src/functions/services/createPickAndShipShipment.ts +++ b/actions/gls-action/src/functions/services/createPickAndShipShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createPickAndShipShipment", + displayMessage: [ + { + code: "en-US", + content: "Create pick and ship shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createShopDeliveryShipment.ts b/actions/gls-action/src/functions/services/createShopDeliveryShipment.ts index 3595eaf..04729ab 100644 --- a/actions/gls-action/src/functions/services/createShopDeliveryShipment.ts +++ b/actions/gls-action/src/functions/services/createShopDeliveryShipment.ts @@ -14,6 +14,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createShopDeliveryShipment", + displayMessage: [ + { + code: "en-US", + content: "Create shop delivery shipment" + } + ], name: [ { code: "en-US", @@ -59,7 +65,3 @@ export default (sdk: ActionSdk) => { }, ) } - - - - diff --git a/actions/gls-action/src/functions/services/createShopReturnShipment.ts b/actions/gls-action/src/functions/services/createShopReturnShipment.ts index df3a823..7e48cb8 100644 --- a/actions/gls-action/src/functions/services/createShopReturnShipment.ts +++ b/actions/gls-action/src/functions/services/createShopReturnShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createShopReturnShipment", + displayMessage: [ + { + code: "en-US", + content: "Create shop return shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createSignatureShipment.ts b/actions/gls-action/src/functions/services/createSignatureShipment.ts index 2842f38..1160097 100644 --- a/actions/gls-action/src/functions/services/createSignatureShipment.ts +++ b/actions/gls-action/src/functions/services/createSignatureShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createSignatureShipment", + displayMessage: [ + { + code: "en-US", + content: "Create signature shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/services/createTyreShipment.ts b/actions/gls-action/src/functions/services/createTyreShipment.ts index 4e47b37..ef3433b 100644 --- a/actions/gls-action/src/functions/services/createTyreShipment.ts +++ b/actions/gls-action/src/functions/services/createTyreShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createTyreShipment", + displayMessage: [ + { + code: "en-US", + content: "Create tyre shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/updateParcelWeight.ts b/actions/gls-action/src/functions/updateParcelWeight.ts index 3fbbbfa..2841e1f 100644 --- a/actions/gls-action/src/functions/updateParcelWeight.ts +++ b/actions/gls-action/src/functions/updateParcelWeight.ts @@ -12,6 +12,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "updateParcelWeight", + displayMessage: [ + { + code: "en-US", + content: "Update parcel weight" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/utils/createAddress.ts b/actions/gls-action/src/functions/utils/createAddress.ts index 77e0461..ec4fcd6 100644 --- a/actions/gls-action/src/functions/utils/createAddress.ts +++ b/actions/gls-action/src/functions/utils/createAddress.ts @@ -2,10 +2,16 @@ import {ActionSdk} from "@code0-tech/hercules"; import {AddressSchema} from "../../types/glsAddress"; export default (sdk: ActionSdk) => { - sdk.registerFunctionDefinitions( + return sdk.registerFunctionDefinitions( { definition: { runtimeName: "createAddress", + displayMessage: [ + { + code: "en-US", + content: "Create address" + } + ], signature: "Name1: string, CountryCode: string, City: string, Street: string, ZIPCode: string, Name2?: string, Name3?: string, Province?: string, StreetNumber?: string, ContactPerson?: string, FixedLinePhonenumber?: string, MobilePhonenumber?: string, Email?: string): GLS_ADDRESS", name: [ { diff --git a/actions/gls-action/src/functions/utils/createConsignee.ts b/actions/gls-action/src/functions/utils/createConsignee.ts index eab02a9..a0dc488 100644 --- a/actions/gls-action/src/functions/utils/createConsignee.ts +++ b/actions/gls-action/src/functions/utils/createConsignee.ts @@ -3,10 +3,16 @@ import {AddressSchema} from "../../types/glsAddress"; import {ConsigneeSchema} from "../../types/glsConsignee"; export default (sdk: ActionSdk) => { - sdk.registerFunctionDefinitions( + return sdk.registerFunctionDefinitions( { definition: { runtimeName: "createConsignee", + displayMessage: [ + { + code: "en-US", + content: "Create consignee" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/utils/createCustomContent.ts b/actions/gls-action/src/functions/utils/createCustomContent.ts index 898e656..ac08b1c 100644 --- a/actions/gls-action/src/functions/utils/createCustomContent.ts +++ b/actions/gls-action/src/functions/utils/createCustomContent.ts @@ -6,6 +6,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createCustomContent", + displayMessage: [ + { + code: "en-US", + content: "Create custom content" + } + ], signature: "(barcodeContentType: \"TRACK_ID\"|\"GLS_SHIPMENT_REFERENCE\", customerLogo: string, hideShipperAddress?: boolean, barcodeType?: \"EAN_128\"|\"CODE_39\", barcode?: string): GLS_CUSTOM_CONTENT", name: [ { diff --git a/actions/gls-action/src/functions/utils/createPrintingOptions.ts b/actions/gls-action/src/functions/utils/createPrintingOptions.ts index d41f551..94dae71 100644 --- a/actions/gls-action/src/functions/utils/createPrintingOptions.ts +++ b/actions/gls-action/src/functions/utils/createPrintingOptions.ts @@ -2,10 +2,16 @@ import {ActionSdk} from "@code0-tech/hercules"; import {PrintingOptions, ReturnLabels} from "../../types/glsPrintingOptions"; export default (sdk: ActionSdk) => { - sdk.registerFunctionDefinitions( + return sdk.registerFunctionDefinitions( { definition: { runtimeName: "createPrintingOptions", + displayMessage: [ + { + code: "en-US", + content: "Create printing options" + } + ], signature: "(returnLabels: RETURN_LABELS): GLS_PRINTING_OPTIONS", name: [ { diff --git a/actions/gls-action/src/functions/utils/createShipmentUnit.ts b/actions/gls-action/src/functions/utils/createShipmentUnit.ts index 9d145c7..a991e9b 100644 --- a/actions/gls-action/src/functions/utils/createShipmentUnit.ts +++ b/actions/gls-action/src/functions/utils/createShipmentUnit.ts @@ -3,10 +3,16 @@ import { UnitService } from "../../types/glsUnitService"; import {ShipmentUnit} from "../../types/glsShipmentUnit"; export default (sdk: ActionSdk) => { - sdk.registerFunctionDefinitions( + return sdk.registerFunctionDefinitions( { definition: { runtimeName: "createShipmentUnit", + displayMessage: [ + { + code: "en-US", + content: "Create shipment unit" + } + ], signature: "(weight: number, shipmentUnitReference?: string, partnerParcelNumber?: string, note1?: string, note2?: string, shipmentUnitService: GLS_SHIPMENT_UNIT_SERVICE): GLS_SHIPMENT_UNIT", name: [ { diff --git a/actions/gls-action/src/functions/validateShipment.ts b/actions/gls-action/src/functions/validateShipment.ts index 5088640..1b7348c 100644 --- a/actions/gls-action/src/functions/validateShipment.ts +++ b/actions/gls-action/src/functions/validateShipment.ts @@ -12,6 +12,18 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "validateShipment", + documentation: [ + { + code: "en-US", + content: "Validates a shipment against the GLS API without creating it. Use this before `createShipment` functions to catch errors early." + } + ], + displayMessage: [ + { + code: "en-US", + content: "Validate shipment" + } + ], name: [ { code: "en-US", diff --git a/actions/gls-action/tsconfig.json b/actions/gls-action/tsconfig.json index 8394117..d3ec800 100644 --- a/actions/gls-action/tsconfig.json +++ b/actions/gls-action/tsconfig.json @@ -3,5 +3,5 @@ "compilerOptions": { "outDir": "dist" }, - "include": ["src"] + "include": ["src", "scripts"] } \ No newline at end of file diff --git a/actions/gls-action/vite.config.ts b/actions/gls-action/vite.config.ts index f258811..7ab94be 100644 --- a/actions/gls-action/vite.config.ts +++ b/actions/gls-action/vite.config.ts @@ -10,7 +10,7 @@ export default defineConfig({ rollupOptions: { input: { main: resolve(__dirname, 'src/index.ts'), - generateTypes: resolve(__dirname, 'scripts/generateTypes.ts') + generateDocs: resolve(__dirname, 'scripts/generateDocs.ts') }, external: [ 'fs', diff --git a/docs/Actions/GLS/functions.mdx b/docs/Actions/GLS/functions.mdx new file mode 100644 index 0000000..6d45a26 --- /dev/null +++ b/docs/Actions/GLS/functions.mdx @@ -0,0 +1,2625 @@ +--- +title: Functions +description: All functions registered by the GLS Action. +--- + +The GLS Action exposes 26 functions grouped into three categories: + +- **Builder functions** — Construct data objects (no API call) +- **Shipment functions** — Create different types of GLS shipments (calls GLS API) +- **API functions** — Query or modify shipments (calls GLS API) + +--- + +## Builder functions + +### `createShipmentUnit` + + + + + +--- + +### `createPrintingOptions` + + + + + +--- + +### `createCustomContent` + + + + + +--- + +### `createConsignee` + + + + + +--- + +### `createAddress` + + + + + +--- + +## Shipment functions + +All shipment functions accept a common set of parameters in addition to their type-specific parameters. They call the GLS ShipIT API (`POST /rs/shipments`) and return a `GLS_CREATE_PARCELS_RESPONSE`. + +**Common parameters for all shipment functions:** + +| Parameter | Type | Required | Description | +|-------------------|-------------------------------|----------|----------------------------------------------------| +| `shipment` | GLS_SHIPMENT_WITHOUT_SERVICES | **Yes** | Shipment data (consignee, shipper, units, product) | +| `printingOptions` | GLS_PRINTING_OPTIONS | **Yes** | Label format settings | +| `returnOptions` | GLS_RETURN_OPTIONS | No | Whether to return print data and routing info | +| `customContent` | GLS_CUSTOM_CONTENT | No | Custom logo and barcode settings | + +--- + +### `createTyreShipment` + + + + + +--- + +### `createSignatureShipment` + + + + + +--- + +### `createShopReturnShipment` + + + + + +--- + +### `createShopDeliveryShipment` + + + + + +--- + +### `createPickAndShipShipment` + + + + + +--- + +### `createIdentShipment` + + + + + +--- + +### `createIdentPinShipment` + + + + + +--- + +### `createGuaranteed24Shipment` + + + + + +--- + +### `createFlexDeliveryShipment` + + + + + +--- + +### `createExchangeShipment` + + + + + +--- + +### `createDepositShipment` + + + + + +--- + +### `createDeliverySaturdayShipment` + + + + + +--- + +### `createDeliveryNextWorkingDayShipment` + + + + + +--- + +### `createDeliveryAtWorkShipment` + + + + + +--- + +### `createAddresseeOnlyShipment` + + + + + +--- + + ## API functions + +### `validateShipment` + +Validates a shipment against the GLS API without creating it. Use this before `createShipment*` functions to catch errors early. + + + +--- + +### `updateParcelWeight` + + + + + +--- + +### `reprintParcel` + + + + + +--- + +### `getEndOfDayReport` + + + + + +--- + +### `getAllowedServices` + + + + + +--- + +### `cancelShipment` + + + + + +--- diff --git a/docs/Actions/GLS/types.mdx b/docs/Actions/GLS/types.mdx index c5d5e18..8188311 100644 --- a/docs/Actions/GLS/types.mdx +++ b/docs/Actions/GLS/types.mdx @@ -1,6 +1,6 @@ --- title: Datatypes -description: All data types registered by the GLS Action — field references and descriptions. +description: All data types registered by the GLS Action. --- import {TypeTable} from "fumadocs-ui/components/type-table"; @@ -24,6 +24,7 @@ typeDescriptionLink: '#gls_shipment', }, }} /> + # GLS_VALIDATE_SHIPMENT_RESPONSE_DATA No documentation provided for this type. @@ -43,6 +44,7 @@ typeDescriptionLink: '#gls_validate_shipment_response_datavalidationresult', }, }} /> + # GLS_VALIDATE_SHIPMENT_RESPONSE_DATA$validationResult No documentation provided for this type. @@ -56,6 +58,7 @@ typeDescriptionLink: '#gls_validate_shipment_response_datavalidationresultissues }, }} /> + # GLS_VALIDATE_SHIPMENT_RESPONSE_DATA$validationResult$Issues No documentation provided for this type. @@ -80,6 +83,7 @@ No documentation provided for this type. }, }} /> + # GLS_UPDATE_PARCEL_WEIGHT_REQUEST_DATA No documentation provided for this type. @@ -122,6 +126,7 @@ No documentation provided for this type. }, }} /> + # GLS_UPDATE_PARCEL_WEIGHT_RESPONSE_DATA No documentation provided for this type. @@ -134,6 +139,7 @@ No documentation provided for this type. }, }} /> + # GLS_UNIT_SERVICE No documentation provided for this type. @@ -175,6 +181,7 @@ typeDescriptionLink: '#gls_unit_servicelimitedquantities', }, }} /> + # GLS_UNIT_SERVICE$LimitedQuantities No documentation provided for this type. @@ -187,12 +194,14 @@ No documentation provided for this type. }, }} /> + # GLS_UNIT_SERVICE$ExWorks No documentation provided for this type. + # GLS_UNIT_SERVICE$HazardousGoods No documentation provided for this type. @@ -206,6 +215,7 @@ typeDescriptionLink: '#gls_unit_servicehazardousgoodsharzardousgood', }, }} /> + # GLS_UNIT_SERVICE$HazardousGoods$HarzardousGood No documentation provided for this type. @@ -224,6 +234,7 @@ No documentation provided for this type. }, }} /> + # GLS_UNIT_SERVICE$AddonLiability No documentation provided for this type. @@ -248,6 +259,7 @@ No documentation provided for this type. }, }} /> + # GLS_UNIT_SERVICE$Cash No documentation provided for this type. @@ -272,6 +284,7 @@ No documentation provided for this type. }, }} /> + # GLS_SHIPPER No documentation provided for this type. @@ -292,6 +305,7 @@ typeDescriptionLink: '#gls_address', }, }} /> + # GLS_SHIPMENT_UNIT No documentation provided for this type. @@ -335,6 +349,7 @@ typeDescriptionLink: '#gls_shipment_unitservice', }, }} /> + # GLS_SHIPMENT_UNIT$Service No documentation provided for this type. @@ -376,6 +391,7 @@ typeDescriptionLink: '#gls_shipment_unitservicelimitedquantities', }, }} /> + # GLS_SHIPMENT_UNIT$Service$LimitedQuantities No documentation provided for this type. @@ -388,12 +404,14 @@ No documentation provided for this type. }, }} /> + # GLS_SHIPMENT_UNIT$Service$ExWorks No documentation provided for this type. + # GLS_SHIPMENT_UNIT$Service$HazardousGoods No documentation provided for this type. @@ -407,6 +425,7 @@ typeDescriptionLink: '#gls_shipment_unitservicehazardousgoodsharzardousgood', }, }} /> + # GLS_SHIPMENT_UNIT$Service$HazardousGoods$HarzardousGood No documentation provided for this type. @@ -425,6 +444,7 @@ No documentation provided for this type. }, }} /> + # GLS_SHIPMENT_UNIT$Service$AddonLiability No documentation provided for this type. @@ -449,6 +469,7 @@ No documentation provided for this type. }, }} /> + # GLS_SHIPMENT_UNIT$Service$Cash No documentation provided for this type. @@ -473,6 +494,7 @@ No documentation provided for this type. }, }} /> + # GLS_SHIPMENT No documentation provided for this type. @@ -556,6 +578,7 @@ typeDescriptionLink: '#gls_shipmentreturn', }, }} /> + # GLS_SHIPMENT$Return No documentation provided for this type. @@ -569,6 +592,7 @@ typeDescriptionLink: '#gls_address', }, }} /> + # GLS_SHIPMENT_WITHOUT_SERVICES No documentation provided for this type. @@ -645,6 +669,7 @@ typeDescriptionLink: '#gls_shipment_without_servicesreturn', }, }} /> + # GLS_SHIPMENT_WITHOUT_SERVICES$Return No documentation provided for this type. @@ -658,6 +683,7 @@ typeDescriptionLink: '#gls_address', }, }} /> + # GLS_RETURN_OPTIONS No documentation provided for this type. @@ -676,6 +702,7 @@ No documentation provided for this type. }, }} /> + # GLS_REPRINT_PARCEL_REQUEST_DATA No documentation provided for this type. @@ -725,6 +752,7 @@ typeDescriptionLink: '#gls_reprint_parcel_request_dataprintingoptions', }, }} /> + # GLS_REPRINT_PARCEL_REQUEST_DATA$PrintingOptions No documentation provided for this type. @@ -738,6 +766,7 @@ typeDescriptionLink: '#gls_reprint_parcel_request_dataprintingoptionsreturnlabel }, }} /> + # GLS_REPRINT_PARCEL_REQUEST_DATA$PrintingOptions$ReturnLabels No documentation provided for this type. @@ -756,6 +785,7 @@ No documentation provided for this type. }, }} /> + # GLS_REPRINT_PARCEL_RESPONSE_DATA No documentation provided for this type. @@ -769,6 +799,7 @@ typeDescriptionLink: '#gls_reprint_parcel_response_datacreatedshipment', }, }} /> + # GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment No documentation provided for this type. @@ -807,6 +838,7 @@ typeDescriptionLink: '#gls_reprint_parcel_response_datacreatedshipmentprintdata' }, }} /> + # GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$PrintData No documentation provided for this type. @@ -825,6 +857,7 @@ No documentation provided for this type. }, }} /> + # GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData No documentation provided for this type. @@ -863,6 +896,7 @@ typeDescriptionLink: '#gls_reprint_parcel_response_datacreatedshipmentparceldata }, }} /> + # GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData$RoutingInfo No documentation provided for this type. @@ -899,6 +933,7 @@ No documentation provided for this type. }, }} /> + # GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData$Barcodes No documentation provided for this type. @@ -929,6 +964,7 @@ No documentation provided for this type. }, }} /> + # GLS_PRINTING_OPTIONS No documentation provided for this type. @@ -955,6 +991,7 @@ typeDescriptionLink: '#gls_printing_optionsdefineprinter', }, }} /> + # GLS_PRINTING_OPTIONS$DefinePrinter No documentation provided for this type. @@ -973,6 +1010,7 @@ No documentation provided for this type. }, }} /> + # GLS_PRINTING_OPTIONS$ReturnLabels No documentation provided for this type. @@ -991,6 +1029,7 @@ No documentation provided for this type. }, }} /> + # GLS_END_OF_DAY_REQUEST_DATA No documentation provided for this type. @@ -1003,6 +1042,7 @@ No documentation provided for this type. }, }} /> + # GLS_END_OF_DAY_RESPONSE_DATA No documentation provided for this type. @@ -1016,6 +1056,7 @@ typeDescriptionLink: '#gls_end_of_day_response_datashipments', }, }} /> + # GLS_END_OF_DAY_RESPONSE_DATA$Shipments No documentation provided for this type. @@ -1055,6 +1096,7 @@ typeDescriptionLink: '#gls_end_of_day_response_datashipmentsshipmentunit', }, }} /> + # GLS_END_OF_DAY_RESPONSE_DATA$Shipments$ShipmentUnit No documentation provided for this type. @@ -1079,6 +1121,7 @@ No documentation provided for this type. }, }} /> + # GLS_END_OF_DAY_RESPONSE_DATA$Shipments$Shipper No documentation provided for this type. @@ -1098,6 +1141,7 @@ typeDescriptionLink: '#gls_address', }, }} /> + # GLS_END_OF_DAY_RESPONSE_DATA$Shipments$Consignee No documentation provided for this type. @@ -1111,6 +1155,7 @@ typeDescriptionLink: '#gls_address', }, }} /> + # GLS_CUSTOM_CONTENT No documentation provided for this type. @@ -1147,6 +1192,7 @@ No documentation provided for this type. }, }} /> + # GLS_CREATE_PARCELS_RESPONSE No documentation provided for this type. @@ -1160,6 +1206,7 @@ typeDescriptionLink: '#gls_create_parcels_responsecreatedshipment', }, }} /> + # GLS_CREATE_PARCELS_RESPONSE$CreatedShipment No documentation provided for this type. @@ -1204,6 +1251,7 @@ typeDescriptionLink: '#gls_create_parcels_responsecreatedshipmentprintdata', }, }} /> + # GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$PrintData No documentation provided for this type. @@ -1222,6 +1270,7 @@ No documentation provided for this type. }, }} /> + # GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData No documentation provided for this type. @@ -1254,6 +1303,7 @@ typeDescriptionLink: '#gls_create_parcels_responsecreatedshipmentparceldatarouti }, }} /> + # GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData$RoutingInfo No documentation provided for this type. @@ -1290,6 +1340,7 @@ No documentation provided for this type. }, }} /> + # GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData$Barcodes No documentation provided for this type. @@ -1320,6 +1371,7 @@ No documentation provided for this type. }, }} /> + # GLS_CONSIGNEE No documentation provided for this type. @@ -1351,6 +1403,7 @@ typeDescriptionLink: '#gls_address', }, }} /> + # GLS_CANCEL_SHIPMENT_REQUEST_DATA No documentation provided for this type. @@ -1363,6 +1416,7 @@ No documentation provided for this type. }, }} /> + # GLS_CANCEL_SHIPMENT_RESPONSE_DATA No documentation provided for this type. @@ -1381,6 +1435,7 @@ No documentation provided for this type. }, }} /> + # GLS_ALLOWED_SERVICES_REQUEST_DATA No documentation provided for this type. @@ -1407,6 +1462,7 @@ typeDescriptionLink: '#gls_allowed_services_request_datadestination', }, }} /> + # GLS_ALLOWED_SERVICES_REQUEST_DATA$Destination No documentation provided for this type. @@ -1425,6 +1481,7 @@ No documentation provided for this type. }, }} /> + # GLS_ALLOWED_SERVICES_REQUEST_DATA$Source No documentation provided for this type. @@ -1443,6 +1500,7 @@ No documentation provided for this type. }, }} /> + # GLS_ALLOWED_SERVICES_RESPONSE_DATA No documentation provided for this type. @@ -1456,6 +1514,7 @@ typeDescriptionLink: '#gls_allowed_services_response_dataallowedservices', }, }} /> + # GLS_ALLOWED_SERVICES_RESPONSE_DATA$AllowedServices No documentation provided for this type. @@ -1474,10 +1533,9 @@ No documentation provided for this type. }, }} /> + # GLS_ADDRESS - -Some Global address documentation -test2 +No documentation provided for this type. + \ No newline at end of file From 958622d40c232490a8810492719f14efb65a88b2 Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Thu, 2 Apr 2026 13:28:32 +0200 Subject: [PATCH 07/17] Add documentation for shipment-related functions --- actions/gls-action/scripts/generateDocs.ts | 10 +- .../src/functions/cancelShipment.ts | 8 +- .../src/functions/getAllowedServices.ts | 8 +- .../src/functions/getEndOfDayReport.ts | 8 +- .../gls-action/src/functions/reprintParcel.ts | 8 +- .../services/createAddresseeOnlyShipment.ts | 8 +- .../services/createDeliveryAtWorkShipment.ts | 8 +- .../createDeliveryNextWorkingDayShipment.ts | 8 +- .../createDeliverySaturdayShipment.ts | 8 +- .../services/createDepositShipment.ts | 8 +- .../services/createExchangeShipment.ts | 8 +- .../services/createFlexDeliveryShipment.ts | 8 +- .../services/createGuaranteed24Shipment.ts | 8 +- .../services/createIdentPinShipment.ts | 8 +- .../functions/services/createIdentShipment.ts | 8 +- .../services/createPickAndShipShipment.ts | 8 +- .../services/createShopDeliveryShipment.ts | 8 +- .../services/createShopReturnShipment.ts | 8 +- .../services/createSignatureShipment.ts | 8 +- .../functions/services/createTyreShipment.ts | 8 +- .../src/functions/updateParcelWeight.ts | 8 +- .../src/functions/utils/createAddress.ts | 6 ++ .../src/functions/utils/createConsignee.ts | 8 +- .../functions/utils/createCustomContent.ts | 6 ++ .../functions/utils/createPrintingOptions.ts | 6 ++ .../src/functions/utils/createShipmentUnit.ts | 6 ++ .../src/functions/validateShipment.ts | 2 +- docs/Actions/GLS/functions.mdx | 96 +++++++++---------- 28 files changed, 225 insertions(+), 75 deletions(-) diff --git a/actions/gls-action/scripts/generateDocs.ts b/actions/gls-action/scripts/generateDocs.ts index 03713b6..c883af2 100644 --- a/actions/gls-action/scripts/generateDocs.ts +++ b/actions/gls-action/scripts/generateDocs.ts @@ -362,11 +362,11 @@ ${JSON.stringify(generateDefinition, null, 4)} } run().then(async (sdk) => { - // writeFileSync( - // "../../docs/Actions/GLS/types.mdx", - // generateDatatypes(), - // "utf8" - // ) + writeFileSync( + "../../docs/Actions/GLS/types.mdx", + generateDatatypes(), + "utf8" + ) writeFileSync( "../../docs/Actions/GLS/functions.mdx", diff --git a/actions/gls-action/src/functions/cancelShipment.ts b/actions/gls-action/src/functions/cancelShipment.ts index 50d562f..a032f4a 100644 --- a/actions/gls-action/src/functions/cancelShipment.ts +++ b/actions/gls-action/src/functions/cancelShipment.ts @@ -7,6 +7,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "cancelShipment", + documentation: [ + { + code: "en-US", + content: "Cancels an existing shipment by its Track ID. Only possible if the parcel has not yet been scanned." + } + ], displayMessage: [ { code: "en-US", @@ -22,7 +28,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Cancels a GLS shipment.", + content: "Cancels an existing shipment by its Track ID. Only possible if the parcel has not yet been scanned.", } ], signature: "(data: GLS_CANCEL_SHIPMENT_REQUEST_DATA): GLS_CANCEL_SHIPMENT_RESPONSE_DATA", diff --git a/actions/gls-action/src/functions/getAllowedServices.ts b/actions/gls-action/src/functions/getAllowedServices.ts index 4754342..545242a 100644 --- a/actions/gls-action/src/functions/getAllowedServices.ts +++ b/actions/gls-action/src/functions/getAllowedServices.ts @@ -12,6 +12,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "getAllowedServices", + documentation: [ + { + code: "en-US", + content: "Returns the GLS services available for a given origin/destination country and ZIP code combination." + } + ], displayMessage: [ { code: "en-US", @@ -27,7 +33,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Returns the allowed GLS services for a given set of parameters.", + content: "Returns the GLS services available for a given origin/destination country and ZIP code combination.", } ], signature: "(data: GLS_ALLOWED_SERVICES_REQUEST_DATA): GLS_ALLOWED_SERVICES_RESPONSE_DATA", diff --git a/actions/gls-action/src/functions/getEndOfDayReport.ts b/actions/gls-action/src/functions/getEndOfDayReport.ts index a5dd7c6..9fe77b9 100644 --- a/actions/gls-action/src/functions/getEndOfDayReport.ts +++ b/actions/gls-action/src/functions/getEndOfDayReport.ts @@ -8,6 +8,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "getEndOfDayReport", + documentation: [ + { + code: "en-US", + content: "Retrieves all shipments dispatched on a given date. Useful for reconciliation and end-of-day processing." + } + ], displayMessage: [ { code: "en-US", @@ -23,7 +29,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Returns the GLS end of day report.", + content: "Retrieves all shipments dispatched on a given date. Useful for reconciliation and end-of-day processing.", } ], signature: "(data: GLS_END_OF_DAY_REQUEST_DATA): GLS_END_OF_DAY_RESPONSE_DATA", diff --git a/actions/gls-action/src/functions/reprintParcel.ts b/actions/gls-action/src/functions/reprintParcel.ts index 9b19744..ea9fc86 100644 --- a/actions/gls-action/src/functions/reprintParcel.ts +++ b/actions/gls-action/src/functions/reprintParcel.ts @@ -12,6 +12,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "reprintParcel", + documentation: [ + { + code: "en-US", + content: "Reprints the label for an existing parcel. Use this if the original label is damaged, lost, or needs to be printed in a different format." + } + ], displayMessage: [ { code: "en-US", @@ -27,7 +33,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Reprints the labels for a GLS parcel.", + content: "Reprints the label for an existing parcel. Use this if the original label is damaged, lost, or needs to be printed in a different format.", } ], signature: "(data: GLS_REPRINT_PARCEL_REQUEST_DATA): GLS_REPRINT_PARCEL_RESPONSE_DATA", diff --git a/actions/gls-action/src/functions/services/createAddresseeOnlyShipment.ts b/actions/gls-action/src/functions/services/createAddresseeOnlyShipment.ts index c1fe032..6b9f5cb 100644 --- a/actions/gls-action/src/functions/services/createAddresseeOnlyShipment.ts +++ b/actions/gls-action/src/functions/services/createAddresseeOnlyShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createAddresseeOnlyShipment", + documentation: [ + { + code: "en-US", + content: "Creates a shipment that can only be delivered to the named addressee (no neighbor delivery)." + } + ], displayMessage: [ { code: "en-US", @@ -30,7 +36,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS addressee only shipment.", + content: "Creates a shipment that can only be delivered to the named addressee (no neighbor delivery).", } ], signature: `(${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createDeliveryAtWorkShipment.ts b/actions/gls-action/src/functions/services/createDeliveryAtWorkShipment.ts index b115393..75be85b 100644 --- a/actions/gls-action/src/functions/services/createDeliveryAtWorkShipment.ts +++ b/actions/gls-action/src/functions/services/createDeliveryAtWorkShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createDeliveryAtWorkShipment", + documentation: [ + { + code: "en-US", + content: "Delivers a parcel to a specific location within a workplace (building, floor, room)." + } + ], displayMessage: [ { code: "en-US", @@ -30,7 +36,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS delivery at work shipment.", + content: "Delivers a parcel to a specific location within a workplace (building, floor, room).", } ], signature: `(recipientName: string, building: string, floor: number, ${DEFAULT_SIGNATURE_FOR_SERVICES}, alternateRecipientName?: string, room?: number, phonenumber?: string): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createDeliveryNextWorkingDayShipment.ts b/actions/gls-action/src/functions/services/createDeliveryNextWorkingDayShipment.ts index 9b2f35d..845ddaa 100644 --- a/actions/gls-action/src/functions/services/createDeliveryNextWorkingDayShipment.ts +++ b/actions/gls-action/src/functions/services/createDeliveryNextWorkingDayShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createDeliveryNextWorkingDayShipment", + documentation: [ + { + code: "en-US", + content: "Creates an EXPRESS shipment for delivery on the next working day (EOB service)." + } + ], displayMessage: [ { code: "en-US", @@ -30,7 +36,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS delivery next working day shipment.", + content: "Creates an EXPRESS shipment for delivery on the next working day (EOB service).", } ], signature: `(${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createDeliverySaturdayShipment.ts b/actions/gls-action/src/functions/services/createDeliverySaturdayShipment.ts index b99436e..ba00235 100644 --- a/actions/gls-action/src/functions/services/createDeliverySaturdayShipment.ts +++ b/actions/gls-action/src/functions/services/createDeliverySaturdayShipment.ts @@ -16,6 +16,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createDeliverySaturdayShipment", + documentation: [ + { + code: "en-US", + content: "Creates an EXPRESS shipment for Saturday delivery." + } + ], displayMessage: [ { code: "en-US", @@ -31,7 +37,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS delivery Saturday shipment.", + content: "Creates an EXPRESS shipment for Saturday delivery.", } ], signature: `(${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createDepositShipment.ts b/actions/gls-action/src/functions/services/createDepositShipment.ts index 99458f4..2307cbf 100644 --- a/actions/gls-action/src/functions/services/createDepositShipment.ts +++ b/actions/gls-action/src/functions/services/createDepositShipment.ts @@ -16,6 +16,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createDepositShipment", + documentation: [ + { + code: "en-US", + content: "Delivers a parcel to a designated deposit location (e.g. a garage or shed) without requiring a signature." + } + ], displayMessage: [ { code: "en-US", @@ -31,7 +37,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS deposit shipment.", + content: "Delivers a parcel to a designated deposit location (e.g. a garage or shed) without requiring a signature.", } ], signature: `(placeOfDeposit: string, ${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createExchangeShipment.ts b/actions/gls-action/src/functions/services/createExchangeShipment.ts index 6915c7c..e9060e5 100644 --- a/actions/gls-action/src/functions/services/createExchangeShipment.ts +++ b/actions/gls-action/src/functions/services/createExchangeShipment.ts @@ -16,6 +16,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createExchangeShipment", + documentation: [ + { + code: "en-US", + content: "Delivers a new parcel while simultaneously picking up an existing one (exchange)." + } + ], displayMessage: [ { code: "en-US", @@ -31,7 +37,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS exchange shipment.", + content: "Delivers a new parcel while simultaneously picking up an existing one (exchange).", } ], signature: `(address: GLS_ADDRESS, ${DEFAULT_SIGNATURE_FOR_SERVICES}, expectedWeight?: number): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createFlexDeliveryShipment.ts b/actions/gls-action/src/functions/services/createFlexDeliveryShipment.ts index 423f13e..9be4468 100644 --- a/actions/gls-action/src/functions/services/createFlexDeliveryShipment.ts +++ b/actions/gls-action/src/functions/services/createFlexDeliveryShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createFlexDeliveryShipment", + documentation: [ + { + code: "en-US", + content: "Creates a shipment with flexible delivery - the recipient can redirect or reschedule delivery." + } + ], displayMessage: [ { code: "en-US", @@ -30,7 +36,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS flex delivery shipment.", + content: "Creates a shipment with flexible delivery - the recipient can redirect or reschedule delivery.", } ], signature: `(${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createGuaranteed24Shipment.ts b/actions/gls-action/src/functions/services/createGuaranteed24Shipment.ts index 3d2964b..f4ce626 100644 --- a/actions/gls-action/src/functions/services/createGuaranteed24Shipment.ts +++ b/actions/gls-action/src/functions/services/createGuaranteed24Shipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createGuaranteed24Shipment", + documentation: [ + { + code: "en-US", + content: "Creates a shipment with guaranteed delivery within 24 hours." + } + ], displayMessage: [ { code: "en-US", @@ -30,7 +36,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS guaranteed 24 shipment.", + content: "Creates a shipment with guaranteed delivery within 24 hours.", } ], signature: `(${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createIdentPinShipment.ts b/actions/gls-action/src/functions/services/createIdentPinShipment.ts index d733edc..881fe57 100644 --- a/actions/gls-action/src/functions/services/createIdentPinShipment.ts +++ b/actions/gls-action/src/functions/services/createIdentPinShipment.ts @@ -16,6 +16,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createIdentPinShipment", + documentation: [ + { + code: "en-US", + content: "Delivers a parcel with PIN and optional birthdate verification." + } + ], displayMessage: [ { code: "en-US", @@ -31,7 +37,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS ident pin shipment.", + content: "Delivers a parcel with PIN and optional birthdate verification.", } ], signature: `(pin: string, ${DEFAULT_SIGNATURE_FOR_SERVICES}, birthDate: string): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createIdentShipment.ts b/actions/gls-action/src/functions/services/createIdentShipment.ts index 14f72ce..f1b99c1 100644 --- a/actions/gls-action/src/functions/services/createIdentShipment.ts +++ b/actions/gls-action/src/functions/services/createIdentShipment.ts @@ -16,6 +16,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createIdentShipment", + documentation: [ + { + code: "en-US", + content: "Delivers a parcel with identity verification - the driver checks the recipient's ID document." + } + ], displayMessage: [ { code: "en-US", @@ -31,7 +37,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS ident shipment.", + content: "Delivers a parcel with identity verification - the driver checks the recipient's ID document.", } ], signature: `(birthDate: string, firstName: string, lastName: string, nationality: string, ${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createPickAndShipShipment.ts b/actions/gls-action/src/functions/services/createPickAndShipShipment.ts index ae79ae8..0836c80 100644 --- a/actions/gls-action/src/functions/services/createPickAndShipShipment.ts +++ b/actions/gls-action/src/functions/services/createPickAndShipShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createPickAndShipShipment", + documentation: [ + { + code: "en-US", + content: "Schedules a pickup from the consignee's address on a given date." + } + ], displayMessage: [ { code: "en-US", @@ -30,7 +36,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS pick and ship shipment.", + content: "Schedules a pickup from the consignee's address on a given date.", } ], signature: `(pickupDate: string, ${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createShopDeliveryShipment.ts b/actions/gls-action/src/functions/services/createShopDeliveryShipment.ts index 04729ab..5e241e6 100644 --- a/actions/gls-action/src/functions/services/createShopDeliveryShipment.ts +++ b/actions/gls-action/src/functions/services/createShopDeliveryShipment.ts @@ -14,6 +14,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createShopDeliveryShipment", + documentation: [ + { + code: "en-US", + content: "Delivers a parcel to a GLS Parcel Shop where the recipient can collect it." + } + ], displayMessage: [ { code: "en-US", @@ -29,7 +35,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS shop delivery shipment.", + content: "Delivers a parcel to a GLS Parcel Shop where the recipient can collect it.", } ], signature: `(parcelShopId: string, ${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createShopReturnShipment.ts b/actions/gls-action/src/functions/services/createShopReturnShipment.ts index 7e48cb8..06c7b0e 100644 --- a/actions/gls-action/src/functions/services/createShopReturnShipment.ts +++ b/actions/gls-action/src/functions/services/createShopReturnShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createShopReturnShipment", + documentation: [ + { + code: "en-US", + content: "Creates a return shipment from a GLS Parcel Shop (customer drops off parcel at a shop)." + } + ], displayMessage: [ { code: "en-US", @@ -30,7 +36,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS shop return shipment.", + content: "Creates a return shipment from a GLS Parcel Shop (customer drops off parcel at a shop).", } ], signature: `(numberOfLabels: number, ${DEFAULT_SIGNATURE_FOR_SERVICES}, returnQR: "PDF" | "PNG" | "ZPL"): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createSignatureShipment.ts b/actions/gls-action/src/functions/services/createSignatureShipment.ts index 1160097..396bb9a 100644 --- a/actions/gls-action/src/functions/services/createSignatureShipment.ts +++ b/actions/gls-action/src/functions/services/createSignatureShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createSignatureShipment", + documentation: [ + { + code: "en-US", + content: "Creates a shipment that requires a recipient signature upon delivery." + } + ], displayMessage: [ { code: "en-US", @@ -30,7 +36,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS signature shipment.", + content: "Creates a shipment that requires a recipient signature upon delivery.", } ], signature: `(${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/services/createTyreShipment.ts b/actions/gls-action/src/functions/services/createTyreShipment.ts index ef3433b..faf6837 100644 --- a/actions/gls-action/src/functions/services/createTyreShipment.ts +++ b/actions/gls-action/src/functions/services/createTyreShipment.ts @@ -15,6 +15,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createTyreShipment", + documentation: [ + { + code: "en-US", + content: "Creates a shipment specifically for tyre/wheel delivery (uses the GLS TyreService)." + } + ], displayMessage: [ { code: "en-US", @@ -30,7 +36,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS tyre shipment.", + content: "Creates a shipment specifically for tyre/wheel delivery (uses the GLS TyreService).", } ], signature: `(${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`, diff --git a/actions/gls-action/src/functions/updateParcelWeight.ts b/actions/gls-action/src/functions/updateParcelWeight.ts index 2841e1f..f1cb59b 100644 --- a/actions/gls-action/src/functions/updateParcelWeight.ts +++ b/actions/gls-action/src/functions/updateParcelWeight.ts @@ -12,6 +12,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "updateParcelWeight", + documentation: [ + { + code: "en-US", + content: "Updates the weight of an already-created parcel. Useful when the final weight is only known after packaging." + } + ], displayMessage: [ { code: "en-US", @@ -27,7 +33,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Updates the weight of a GLS parcel.", + content: "Updates the weight of an already-created parcel. Useful when the final weight is only known after packaging.", } ], signature: "(data: GLS_UPDATE_PARCEL_WEIGHT_REQUEST_DATA): GLS_END_OF_DAY_RESPONSE_DATA", diff --git a/actions/gls-action/src/functions/utils/createAddress.ts b/actions/gls-action/src/functions/utils/createAddress.ts index ec4fcd6..7f37608 100644 --- a/actions/gls-action/src/functions/utils/createAddress.ts +++ b/actions/gls-action/src/functions/utils/createAddress.ts @@ -6,6 +6,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createAddress", + documentation: [ + { + code: "en-US", + content: "Creates a GLS address object (`GLS_ADDRESS`) for use in shipments as consignee, shipper, or return address." + } + ], displayMessage: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/utils/createConsignee.ts b/actions/gls-action/src/functions/utils/createConsignee.ts index a0dc488..6f5f166 100644 --- a/actions/gls-action/src/functions/utils/createConsignee.ts +++ b/actions/gls-action/src/functions/utils/createConsignee.ts @@ -7,6 +7,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createConsignee", + documentation: [ + { + code: "en-US", + content: "Creates a GLS consignee (recipient) object for use in shipments." + } + ], displayMessage: [ { code: "en-US", @@ -22,7 +28,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Creates a GLS consignee object which can be used for shipments.", + content: "Creates a GLS consignee (recipient) object for use in shipments.", } ], signature: "(consigneeId: string, costCenter: string, Address: GLS_ADDRESS, Category: \"BUSINESS\"|\"PRIVATE\"): GLS_CONSIGNEE", diff --git a/actions/gls-action/src/functions/utils/createCustomContent.ts b/actions/gls-action/src/functions/utils/createCustomContent.ts index ac08b1c..23d597b 100644 --- a/actions/gls-action/src/functions/utils/createCustomContent.ts +++ b/actions/gls-action/src/functions/utils/createCustomContent.ts @@ -6,6 +6,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createCustomContent", + documentation: [ + { + code: "en-US", + content: "Creates custom content settings for GLS labels, including logos and barcodes." + } + ], displayMessage: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/utils/createPrintingOptions.ts b/actions/gls-action/src/functions/utils/createPrintingOptions.ts index 94dae71..d4a1170 100644 --- a/actions/gls-action/src/functions/utils/createPrintingOptions.ts +++ b/actions/gls-action/src/functions/utils/createPrintingOptions.ts @@ -6,6 +6,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createPrintingOptions", + documentation: [ + { + code: "en-US", + content: "Creates GLS printing options that control how labels are generated." + } + ], displayMessage: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/utils/createShipmentUnit.ts b/actions/gls-action/src/functions/utils/createShipmentUnit.ts index a991e9b..75c0368 100644 --- a/actions/gls-action/src/functions/utils/createShipmentUnit.ts +++ b/actions/gls-action/src/functions/utils/createShipmentUnit.ts @@ -7,6 +7,12 @@ export default (sdk: ActionSdk) => { { definition: { runtimeName: "createShipmentUnit", + documentation: [ + { + code: "en-US", + content: "Creates a GLS shipment unit (an individual parcel within a shipment)." + } + ], displayMessage: [ { code: "en-US", diff --git a/actions/gls-action/src/functions/validateShipment.ts b/actions/gls-action/src/functions/validateShipment.ts index 1b7348c..153d48c 100644 --- a/actions/gls-action/src/functions/validateShipment.ts +++ b/actions/gls-action/src/functions/validateShipment.ts @@ -33,7 +33,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Validates a GLS shipment.", + content: "Validates a shipment against the GLS API without creating it. Use this before `createShipment` functions to catch errors early.", } ], signature: "(data: GLS_VALIDATE_SHIPMENT_REQUEST_DATA): GLS_VALIDATE_SHIPMENT_RESPONSE_DATA", diff --git a/docs/Actions/GLS/functions.mdx b/docs/Actions/GLS/functions.mdx index 6d45a26..0acfd75 100644 --- a/docs/Actions/GLS/functions.mdx +++ b/docs/Actions/GLS/functions.mdx @@ -15,7 +15,7 @@ The GLS Action exposes 26 functions grouped into three categories: ### `createShipmentUnit` - +Creates a GLS shipment unit (an individual parcel within a shipment). Date: Thu, 2 Apr 2026 13:30:37 +0200 Subject: [PATCH 08/17] Rename documentation generation script for clarity --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index bed8ff4..4eb0488 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,7 @@ "packageManager": "npm@11.12.1", "scripts": { "build": "npm run build --workspaces --if-present", - "docs:generate": "npm run docs:generate --workspaces --if-present", + "generate:docs": "npm run generate:docs --workspaces --if-present", "start": "turbo run start", "test": "vitest run", "test:watch": "vitest", From 85e18a989bc32ab9e734052ff0a5bb7b43f67558 Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Thu, 2 Apr 2026 13:35:00 +0200 Subject: [PATCH 09/17] Rename documentation generation script for clarity --- docs/Actions/GLS/functions.md | 653 ---------------------------------- 1 file changed, 653 deletions(-) delete mode 100644 docs/Actions/GLS/functions.md diff --git a/docs/Actions/GLS/functions.md b/docs/Actions/GLS/functions.md deleted file mode 100644 index fdb68ee..0000000 --- a/docs/Actions/GLS/functions.md +++ /dev/null @@ -1,653 +0,0 @@ ---- -title: Functions -description: All functions available in the GLS Action with detailed descriptions, parameters, and data flow diagrams. ---- - -# Functions - -The GLS Action exposes **26 functions** grouped into three categories: - -- **Builder functions** — Construct data objects (no API call) -- **Shipment functions** — Create different types of GLS shipments (calls GLS API) -- **API functions** — Query or modify shipments (calls GLS API) - ---- - -## Builder functions - -### `createAddress` - -Creates a GLS address object (`GLS_ADDRESS`) for use in shipments as consignee, shipper, or return address. - -**Signature:** -``` -createAddress( - Name1: string, - CountryCode: string, - City: string, - Street: string, - ZIPCode: string, - Name2?: string, - Name3?: string, - Province?: string, - StreetNumber?: string, - ContactPerson?: string, - FixedLinePhonenumber?: string, - MobilePhonenumber?: string, - Email?: string -): GLS_ADDRESS -``` - -**Parameters:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `Name1` | string (max 40) | **Yes** | Primary name (recipient or company name) | -| `CountryCode` | string (max 2) | **Yes** | ISO alpha-2 country code (e.g. `DE`, `FR`, `GB`) | -| `City` | string (max 40) | **Yes** | City name | -| `Street` | string (min 4) | **Yes** | Street name | -| `ZIPCode` | string (max 10) | **Yes** | Postal/ZIP code | -| `Name2` | string (max 40) | No | Additional name line (e.g. department) | -| `Name3` | string (max 40) | No | Additional name line (e.g. c/o) | -| `Province` | string (max 40) | No | State or province | -| `StreetNumber` | string (max 40) | No | House/building number | -| `ContactPerson` | string (min 6, max 40) | No | Contact person at this address | -| `FixedLinePhonenumber` | string (min 4, max 35) | No | Landline phone number | -| `MobilePhonenumber` | string (min 4, max 35) | No | Mobile phone number | -| `eMail` | string (max 80) | No | Email address | - -**Returns:** [`GLS_ADDRESS`](types.mdx#GLS_ADDRESS) - ---- - -### `createConsignee` - -Creates a GLS consignee (recipient) object for use in shipments. - -**Signature:** -``` -createConsignee( - consigneeId: string, - costCenter: string, - AddressSchema: GLS_ADDRESS, - Category: "BUSINESS" | "PRIVATE" -): GLS_CONSIGNEE -``` - -**Parameters:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `consigneeId` | string (max 40) | **Yes** | Unique ID for the consignee (your internal customer ID) | -| `costCenter` | string (max 80) | **Yes** | Cost center for billing purposes | -| `AddressSchema` | GLS_ADDRESS | **Yes** | The delivery address for this consignee | -| `Category` | `"BUSINESS"` \| `"PRIVATE"` | **Yes** | Whether the consignee is a business or private recipient | - -**Returns:** [`GLS_CONSIGNEE`](types.mdx#GLS_CONSIGNEE) - ---- - -### `createShipmentUnit` - -Creates a GLS shipment unit (an individual parcel within a shipment). - -**Signature:** -``` -createShipmentUnit( - weight: number, - shipmentUnitReference?: string, - partnerParcelNumber?: string, - note1?: string, - note2?: string, - shipmentUnitService: GLS_UNIT_SERVICE -): GLS_SHIPMENT_UNIT -``` - -**Parameters:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `weight` | number (0.10–99) | **Yes** | Weight of the parcel in kilograms | -| `shipmentUnitReference` | string (max 40) | No | Your internal reference for this parcel | -| `partnerParcelNumber` | string (max 50) | No | Partner-assigned parcel number | -| `note1` | string (max 50) | No | Additional note printed on the label (line 1) | -| `note2` | string (max 50) | No | Additional note printed on the label (line 2) | -| `shipmentUnitService` | GLS_UNIT_SERVICE | No | Unit-level services (Cash, AddonLiability, HazardousGoods, etc.) | - -**Returns:** [`GLS_SHIPMENT_UNIT`](types.mdx#gls_shipment_unit) - ---- - -### `createPrintingOptions` - -Creates GLS printing options that control how labels are generated. - -**Signature:** -``` -createPrintingOptions(returnLabels: RETURN_LABELS): GLS_PRINTING_OPTIONS -``` - -**Parameters:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `returnLabels` | RETURN_LABELS | **Yes** | Label format configuration | - -`RETURN_LABELS` fields: - -| Field | Values | Description | -|-------|--------|-------------| -| `TemplateSet` | `NONE`, `D_200`, `PF_4_I`, `ZPL_200`, `ZPL_300`, ... | Label template set | -| `LabelFormat` | `PDF`, `ZEBRA`, `INTERMEC`, `DATAMAX`, `TOSHIBA`, `PNG` | Output format | - -**Returns:** [`GLS_PRINTING_OPTIONS`](types.mdx#GLS_PRINTING_OPTIONS) - ---- - -### `createCustomContent` - -Creates custom content settings for GLS labels, including logos and barcodes. - -**Signature:** -``` -createCustomContent( - barcodeContentType: "TRACK_ID" | "GLS_SHIPMENT_REFERENCE", - customerLogo: string, - hideShipperAddress?: boolean, - barcodeType?: "EAN_128" | "CODE_39", - barcode?: string -): GLS_CUSTOM_CONTENT -``` - -**Parameters:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `barcodeContentType` | `"TRACK_ID"` \| `"GLS_SHIPMENT_REFERENCE"` | **Yes** | What the barcode encodes | -| `customerLogo` | string | **Yes** | Base64-encoded customer logo image | -| `hideShipperAddress` | boolean | No | Hide the shipper address on the label | -| `barcodeType` | `"EAN_128"` \| `"CODE_39"` | No | Barcode symbology | -| `barcode` | string | No | Custom barcode value | - -**Returns:** [`GLS_CUSTOM_CONTENT`](types.mdx#GLS_CUSTOM_CONTENT) - ---- - -## Shipment functions - -All shipment functions accept a common set of parameters in addition to their type-specific parameters. They call the GLS ShipIT API (`POST /rs/shipments`) and return a `GLS_CREATE_PARCELS_RESPONSE`. - -**Common parameters for all shipment functions:** - -| Parameter | Type | Required | Description | -|-------------------|-------------------------------|----------|----------------------------------------------------| -| `shipment` | GLS_SHIPMENT_WITHOUT_SERVICES | **Yes** | Shipment data (consignee, shipper, units, product) | -| `printingOptions` | GLS_PRINTING_OPTIONS | **Yes** | Label format settings | -| `returnOptions` | GLS_RETURN_OPTIONS | No | Whether to return print data and routing info | -| `customContent` | GLS_CUSTOM_CONTENT | No | Custom logo and barcode settings | - ---- - -### `createShopDeliveryShipment` - -Delivers a parcel to a GLS Parcel Shop where the recipient can collect it. - -**Signature:** -``` -createShopDeliveryShipment( - parcelShopId: string, - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT -): GLS_CREATE_PARCELS_RESPONSE -``` - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `parcelShopId` | string | **Yes** | ID of the target GLS Parcel Shop | - -**Data flow:** -``` -createShopDeliveryShipment - │ - ├── Service: [{ ShopDelivery: { ParcelShopID } }] - │ - └── POST /rs/shipments → GLS_CREATE_PARCELS_RESPONSE -``` - ---- - -### `createShopReturnShipment` - -Creates a return shipment from a GLS Parcel Shop (customer drops off parcel at a shop). - -**Signature:** -``` -createShopReturnShipment( - numberOfLabels: number, - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT, - returnQR?: "PDF" | "PNG" | "ZPL" -): GLS_CREATE_PARCELS_RESPONSE -``` - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `numberOfLabels` | number | **Yes** | Number of return labels to generate | -| `returnQR` | `"PDF"` \| `"PNG"` \| `"ZPL"` | No | Format of the QR code for the return | - ---- - -### `createExchangeShipment` - -Delivers a new parcel while simultaneously picking up an existing one (exchange). - -**Signature:** -``` -createExchangeShipment( - address: GLS_ADDRESS, - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT, - expectedWeight?: number -): GLS_CREATE_PARCELS_RESPONSE -``` - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `address` | GLS_ADDRESS | **Yes** | AddressSchema for the exchange pickup | -| `expectedWeight` | number (min 1) | No | Expected weight of the parcel being returned | - ---- - -### `createDeliveryAtWorkShipment` - -Delivers a parcel to a specific location within a workplace (building, floor, room). - -**Signature:** -``` -createDeliveryAtWorkShipment( - recipientName: string, - building: string, - floor: number, - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT, - alternateRecipientName?: string, - room?: number, - phonenumber?: string -): GLS_CREATE_PARCELS_RESPONSE -``` - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `recipientName` | string (max 40) | **Yes** | Name of the recipient at work | -| `building` | string (max 40) | **Yes** | Building name or number | -| `floor` | number | **Yes** | Floor number | -| `alternateRecipientName` | string (max 40) | No | Alternate recipient if primary is unavailable | -| `room` | number | No | Room number | -| `phonenumber` | string (max 35) | No | Contact phone number | - ---- - -### `createDepositShipment` - -Delivers a parcel to a designated deposit location (e.g. a garage or shed) without requiring a signature. - -**Signature:** -``` -createDepositShipment( - placeOfDeposit: string, - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT -): GLS_CREATE_PARCELS_RESPONSE -``` - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `placeOfDeposit` | string (max 121) | **Yes** | Description of where to deposit the parcel | - ---- - -### `createIdentShipment` - -Delivers a parcel with identity verification — the driver checks the recipient's ID document. - -**Signature:** -``` -createIdentShipment( - birthDate: string, - firstName: string, - lastName: string, - nationality: string, - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT -): GLS_CREATE_PARCELS_RESPONSE -``` - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `birthDate` | ISO date string | **Yes** | Recipient's date of birth | -| `firstName` | string (max 40) | **Yes** | Recipient's first name | -| `lastName` | string (max 40) | **Yes** | Recipient's last name | -| `nationality` | string (max 2) | **Yes** | ISO alpha-2 nationality code | - ---- - -### `createIdentPinShipment` - -Delivers a parcel with PIN and optional birthdate verification. - -**Signature:** -``` -createIdentPinShipment( - pin: string, - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT, - birthDate?: string -): GLS_CREATE_PARCELS_RESPONSE -``` - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `pin` | string (max 4) | **Yes** | 4-digit PIN to verify with recipient | -| `birthDate` | ISO date string | No | Recipient's date of birth (additional check) | - ---- - -### `createPickAndShipShipment` - -Schedules a pickup from the consignee's address on a given date. - -**Signature:** -``` -createPickAndShipShipment( - pickupDate: string, - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT -): GLS_CREATE_PARCELS_RESPONSE -``` - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `pickupDate` | ISO date string | **Yes** | Date when GLS will pick up the parcel | - ---- - -### `createFlexDeliveryShipment` - -Creates a shipment with flexible delivery — the recipient can redirect or reschedule delivery. - -**Signature:** -``` -createFlexDeliveryShipment( - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT -): GLS_CREATE_PARCELS_RESPONSE -``` - -No additional parameters beyond the common ones. - ---- - -### `createSignatureShipment` - -Creates a shipment that requires a recipient signature upon delivery. - -**Signature:** -``` -createSignatureShipment( - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT -): GLS_CREATE_PARCELS_RESPONSE -``` - -No additional parameters beyond the common ones. - ---- - -### `createGuaranteed24Shipment` - -Creates a shipment with guaranteed delivery within 24 hours. - -**Signature:** -``` -createGuaranteed24Shipment( - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT -): GLS_CREATE_PARCELS_RESPONSE -``` - -No additional parameters beyond the common ones. - ---- - -### `createAddresseeOnlyShipment` - -Creates a shipment that can only be delivered to the named addressee (no neighbor delivery). - -**Signature:** -``` -createAddresseeOnlyShipment( - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT -): GLS_CREATE_PARCELS_RESPONSE -``` - -No additional parameters beyond the common ones. - ---- - -### `createTyreShipment` - -Creates a shipment specifically for tyre/wheel delivery (uses the GLS TyreService). - -**Signature:** -``` -createTyreShipment( - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT -): GLS_CREATE_PARCELS_RESPONSE -``` - -No additional parameters beyond the common ones. - ---- - -### `createDeliveryNextWorkingDayShipment` - -Creates an **EXPRESS** shipment for delivery on the next working day (EOB service). - -> **Requirement:** The shipment's `Product` field must be set to `"EXPRESS"`. Setting it to `"PARCEL"` will throw an `INVALID_PRODUCT` error. - -**Signature:** -``` -createDeliveryNextWorkingDayShipment( - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT -): GLS_CREATE_PARCELS_RESPONSE -``` - ---- - -### `createDeliverySaturdayShipment` - -Creates an **EXPRESS** shipment for Saturday delivery. - -> **Requirement:** The shipment's `Product` field must be set to `"EXPRESS"`. Setting it to `"PARCEL"` will throw an `INVALID_PRODUCT` error. - -**Signature:** -``` -createDeliverySaturdayShipment( - shipment: GLS_SHIPMENT_WITHOUT_SERVICES, - printingOptions: GLS_PRINTING_OPTIONS, - returnOptions?: GLS_RETURN_OPTIONS, - customContent?: GLS_CUSTOM_CONTENT -): GLS_CREATE_PARCELS_RESPONSE -``` - ---- - -## API functions - -### `validateShipment` - -Validates a shipment against the GLS API without creating it. Use this before `createShipment*` functions to catch errors early. - -**Signature:** -``` -validateShipment(data: GLS_VALIDATE_SHIPMENT_REQUEST_DATA): GLS_VALIDATE_SHIPMENT_RESPONSE_DATA -``` - -**Data flow:** -``` -validateShipment - │ - └── POST /rs/shipments/validate - │ - ▼ - GLS_VALIDATE_SHIPMENT_RESPONSE_DATA - ├── success: boolean - └── validationResult.Issues[] -``` - -See [Types — GLS_VALIDATE_SHIPMENT_REQUEST_DATA](types.mdx#GLS_VALIDATE_SHIPMENT_REQUEST_DATA) for the input format. - ---- - -### `cancelShipment` - -Cancels an existing shipment by its Track ID. Only possible if the parcel has not yet been scanned. - -**Signature:** -``` -cancelShipment(data: GLS_CANCEL_SHIPMENT_REQUEST_DATA): GLS_CANCEL_SHIPMENT_RESPONSE_DATA -``` - -**Data flow:** -``` -cancelShipment({ TrackID }) - │ - └── POST /rs/shipments/cancel/{TrackID} - │ - ▼ - GLS_CANCEL_SHIPMENT_RESPONSE_DATA - ├── TrackID - └── result: "CANCELLED" | "CANCELLATION_PENDING" | "SCANNED" | "ERROR" -``` - ---- - -### `getAllowedServices` - -Returns the GLS services available for a given origin/destination country and ZIP code combination. - -**Signature:** -``` -getAllowedServices(data: GLS_ALLOWED_SERVICES_REQUEST_DATA): GLS_ALLOWED_SERVICES_RESPONSE_DATA -``` - -**Data flow:** -``` -getAllowedServices({ Source, Destination, ContactID? }) - │ - └── GET /rs/shipments/allowedservices - │ - ▼ - GLS_ALLOWED_SERVICES_RESPONSE_DATA - └── AllowedServices[]: { ServiceName } | { ProductName } -``` - ---- - -### `getEndOfDayReport` - -Retrieves all shipments dispatched on a given date. Useful for reconciliation and end-of-day processing. - -**Signature:** -``` -getEndOfDayReport(data: GLS_END_OF_DAY_REQUEST_DATA): GLS_END_OF_DAY_RESPONSE_DATA -``` - -**Data flow:** -``` -getEndOfDayReport({ date }) - │ - └── GET /rs/shipments/endofday?date={date} - │ - ▼ - GLS_END_OF_DAY_RESPONSE_DATA - └── Shipments[]: { ShippingDate, Product, ConsigneeSchema, ShipperSchema, ShipmentUnit[] } -``` - ---- - -### `updateParcelWeight` - -Updates the weight of an already-created parcel. Useful when the final weight is only known after packaging. - -**Signature:** -``` -updateParcelWeight(data: GLS_UPDATE_PARCEL_WEIGHT_REQUEST_DATA): GLS_UPDATE_PARCEL_WEIGHT_RESPONSE_DATA -``` - -**Data flow:** -``` -updateParcelWeight({ TrackID, Weight }) - │ - └── POST /rs/shipments/updateparcelweight - │ - ▼ - GLS_UPDATE_PARCEL_WEIGHT_RESPONSE_DATA - └── UpdatedWeight: string -``` - ---- - -### `reprintParcel` - -Reprints the label for an existing parcel. Use this if the original label is damaged, lost, or needs to be printed in a different format. - -**Signature:** -``` -reprintParcel(data: GLS_REPRINT_PARCEL_REQUEST_DATA): GLS_REPRINT_PARCEL_RESPONSE_DATA -``` - -**Data flow:** -``` -reprintParcel({ TrackID, CreationDate, PrintingOptions }) - │ - └── POST /rs/shipments/reprintparcel - │ - ▼ - GLS_REPRINT_PARCEL_RESPONSE_DATA - └── CreatedShipment - ├── ParcelData[].TrackID - ├── ParcelData[].Barcodes - └── PrintData[].Data ← new base64-encoded label -``` From e60d4f4590ff6a3f6b59b0617715240f7589d141 Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Thu, 2 Apr 2026 13:37:57 +0200 Subject: [PATCH 10/17] Fix links --- docs/Actions/GLS/overview.md | 2 +- docs/Actions/GLS/quick-start.md | 6 +++--- docs/Actions/GLS/troubleshooting.md | 2 +- docs/index.mdx | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/Actions/GLS/overview.md b/docs/Actions/GLS/overview.md index 61f2350..6b05243 100644 --- a/docs/Actions/GLS/overview.md +++ b/docs/Actions/GLS/overview.md @@ -90,7 +90,7 @@ GLS_CREATE_PARCELS_RESPONSE ← tracking IDs, barcode data, print data, routing - [Quick Start](quick-start.md) — Create your first shipment in a few steps - [Configuration](configs.md) — Full list of configuration options and how to get credentials -- [Functions](functions.md) — All available functions with parameter details +- [Functions](functions.mdx) — All available functions with parameter details - [Types](types.mdx) — All data types used in the GLS Action - [Events](events.md) — Events emitted by the GLS Action - [Common Use Cases](use-cases.md) — Example flows for real-world scenarios diff --git a/docs/Actions/GLS/quick-start.md b/docs/Actions/GLS/quick-start.md index 60e2c8f..80fab6f 100644 --- a/docs/Actions/GLS/quick-start.md +++ b/docs/Actions/GLS/quick-start.md @@ -128,7 +128,7 @@ The `GLS_CREATE_PARCELS_RESPONSE` contains everything you need: ## Common next steps -- [Validate before creating](functions.md#validateShipment) — Call `validateShipment` first to catch errors before committing -- [Cancel a shipment](functions.md#cancelShipment) — Use `cancelShipment` with the `TrackID` if something changes -- [Reprint a label](functions.md#reprintParcel) — Use `reprintParcel` if a label is lost or damaged +- [Validate before creating](functions.mdx#validateShipment) — Call `validateShipment` first to catch errors before committing +- [Cancel a shipment](functions.mdx#cancelShipment) — Use `cancelShipment` with the `TrackID` if something changes +- [Reprint a label](functions.mdx#reprintParcel) — Use `reprintParcel` if a label is lost or damaged - [Common Use Cases](use-cases.md) — End-to-end examples for real-world scenarios diff --git a/docs/Actions/GLS/troubleshooting.md b/docs/Actions/GLS/troubleshooting.md index 947344f..ec8d12c 100644 --- a/docs/Actions/GLS/troubleshooting.md +++ b/docs/Actions/GLS/troubleshooting.md @@ -30,7 +30,7 @@ A: The action supports all major GLS shipment types and services, including: - Tyre service, addressee-only delivery - Saturday and next-working-day delivery (EXPRESS only) -See [Functions](functions.md) for the complete list. +See [Functions](functions.mdx) for the complete list. --- diff --git a/docs/index.mdx b/docs/index.mdx index 31e854a..6ddc0a0 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -36,7 +36,7 @@ Before using any action from Centaurus, make sure you have: - [Installation Guide](installation.md) — How to deploy an action on your self-hosted instance - [GLS Action Overview](Actions/GLS/overview.md) — Get started with the GLS shipping integration - [GLS Configuration](Actions/GLS/configs.md) — API keys and configuration options -- [GLS Functions](Actions/GLS/functions.md) — All available functions and their parameters +- [GLS Functions](Actions/GLS/functions.mdx) — All available functions and their parameters - [GLS Types](Actions/GLS/types.mdx) — Data types used across the GLS action - [GLS Events](Actions/GLS/events.md) — Events emitted by the GLS action - [Common Use Cases](Actions/GLS/use-cases.md) — Example workflows using the GLS action From 49740338d9c264b1a308401b28357af09a02e242 Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Thu, 2 Apr 2026 15:28:04 +0200 Subject: [PATCH 11/17] Add testing for more docs --- actions/gls-action/test/index.test.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/actions/gls-action/test/index.test.ts b/actions/gls-action/test/index.test.ts index b1e74c4..f11dcc9 100644 --- a/actions/gls-action/test/index.test.ts +++ b/actions/gls-action/test/index.test.ts @@ -53,6 +53,7 @@ describe("withSdkMock", () => { }); await sdk.registerFlowTypes({ + signature: "", identifier: "Flow1", editable: false, }); @@ -62,7 +63,7 @@ describe("withSdkMock", () => { ]); expect(state.flowTypes).toEqual([ - {identifier: "Flow1", editable: false}, + {identifier: "Flow1", editable: false, signature: ""}, ]); }); @@ -94,6 +95,7 @@ describe("withSdkMock", () => { state.registeredFunctionDefinitions?.forEach(value => { expect(value.definition.name || [], `${value.definition.runtimeName}: Name should be set`).not.toHaveLength(0) expect(value.definition.description || [], `${value.definition.runtimeName}: Description should be set`).not.toHaveLength(0) + expect(value.definition.documentation || [], `${value.definition.runtimeName}: Documentation should be set`).not.toHaveLength(0) value.definition.parameters?.forEach(param => { expect(param.name || [], `${value.definition.runtimeName} parameter ${param.runtimeName}: Name should be set`).not.toHaveLength(0) expect(param.description || [], `${value.definition.runtimeName} parameter ${param.runtimeName}: Description should be set`).not.toHaveLength(0) From b7e9ff2b4ff544dc1b272173bbce15ad05fe74d2 Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Thu, 2 Apr 2026 16:15:17 +0200 Subject: [PATCH 12/17] Enhance documentation generation with parameter details and return types for GLS functions --- actions/gls-action/scripts/generateDocs.ts | 72 +++++ .../services/createShopReturnShipment.ts | 6 +- .../src/functions/utils/createAddress.ts | 2 +- docs/Actions/GLS/functions.mdx | 302 +++++++++++++++++- 4 files changed, 375 insertions(+), 7 deletions(-) diff --git a/actions/gls-action/scripts/generateDocs.ts b/actions/gls-action/scripts/generateDocs.ts index c883af2..85e3eff 100644 --- a/actions/gls-action/scripts/generateDocs.ts +++ b/actions/gls-action/scripts/generateDocs.ts @@ -255,6 +255,54 @@ interface FunctionDefinition { } async function generateFunctions(sdk: ActionSdk): Promise { + function getParamInfo(signature: string, paramName: string): { optional: boolean; type: string | null } { + const paramsMatch = signature.match(/\((.*)\)/s); + if (!paramsMatch) { + return {optional: false, type: null}; + } + + const params = paramsMatch[1].split(","); + + for (const param of params) { + const trimmed = param.trim(); + + // Match: name?: type OR name: type + const match = trimmed.match(new RegExp(`${paramName}\s*(\\?)?\\s*:\\s*(.+)`)); + if (match) { + const isOptional = match[1] === "?"; + const type = match[2].trim(); + + return { + optional: isOptional, + type + }; + } + } + + return {optional: false, type: null}; + } + + function generateMarkdownTable(headers: string[], rows: string[][]) { + const headerRow = `| ${headers.join(' | ')} |`; + const separator = `| ${headers.map(() => '---').join(' | ')} |`; + const bodyRows = rows.map(row => `| ${row.join(' | ')} |`); + + return [headerRow, separator, ...bodyRows].join('\n'); + } + function getLinkFromType(typeName?: string) { + if (!typeName || !typeName.startsWith("GLS_")) return typeName + switch (typeName) { // Some edge cases + case "SHIPMENT_UNIT_SERVICE": { + typeName = "SHIPMENT_UNIT$Service" + break + } + } + const normalizedName = typeName.toLowerCase() + .replace(/-/g, "_") + .replace(/\$/g, ""); + return `[${typeName}](./types.mdx#${normalizedName})` + } + async function loadFunctions(modules: Record Promise>) { for (const path in modules) { @@ -343,9 +391,33 @@ All shipment functions accept a common set of parameters in addition to their ty displayMessages: definition.displayMessage } + const headers = ["Parameter", "Name", "Type", "Required", "Description"] + + let rows = [] + + definition.parameters.forEach(param => { + const paramInfo = getParamInfo(definition.signature, param.runtimeName); + + paramInfo.type = getLinkFromType(paramInfo.type); + + rows.push([ + param.runtimeName, + param.name[0].content, + paramInfo.type?.replace(/\|/g, "\\|") || "Unknown", + paramInfo.optional ? "No" : "Yes", + param.description[0].content + ]) + }) + generatedDoc += ` ### \`${definition.runtimeName}\` +${generateMarkdownTable(headers, rows)} + +Return Type: ${getLinkFromType(definition.signature.split("):")[1].trim())} + +# + ${definition.documentation?.at(0).content || ""} { signature: `(numberOfLabels: number, ${DEFAULT_SIGNATURE_FOR_SERVICES}, returnQR: "PDF" | "PNG" | "ZPL"): GLS_CREATE_PARCELS_RESPONSE`, parameters: [ { - runtimeName: "parcelShopId", + runtimeName: "numberOfLabels", name: [ { code: "en-US", - content: "Parcel shop Id", + content: "The number of labels", } ], description: [ { code: "en-US", - content: "The ID of the parcel shop where the shipment should be delivered.", + content: "The number of labels to be created for the return shipment.", } ] }, diff --git a/actions/gls-action/src/functions/utils/createAddress.ts b/actions/gls-action/src/functions/utils/createAddress.ts index 7f37608..10d3f7d 100644 --- a/actions/gls-action/src/functions/utils/createAddress.ts +++ b/actions/gls-action/src/functions/utils/createAddress.ts @@ -18,7 +18,7 @@ export default (sdk: ActionSdk) => { content: "Create address" } ], - signature: "Name1: string, CountryCode: string, City: string, Street: string, ZIPCode: string, Name2?: string, Name3?: string, Province?: string, StreetNumber?: string, ContactPerson?: string, FixedLinePhonenumber?: string, MobilePhonenumber?: string, Email?: string): GLS_ADDRESS", + signature: "(Name1: string, CountryCode: string, City: string, Street: string, ZIPCode: string, Name2?: string, Name3?: string, Province?: string, StreetNumber?: string, ContactPerson?: string, FixedLinePhonenumber?: string, MobilePhonenumber?: string, Email?: string): GLS_ADDRESS", name: [ { code: "en-US", diff --git a/docs/Actions/GLS/functions.mdx b/docs/Actions/GLS/functions.mdx index 0acfd75..0da0969 100644 --- a/docs/Actions/GLS/functions.mdx +++ b/docs/Actions/GLS/functions.mdx @@ -15,6 +15,19 @@ The GLS Action exposes 26 functions grouped into three categories: ### `createShipmentUnit` +| Parameter | Name | Type | Required | Description | +| --- | --- | --- | --- | --- | +| weight | Weight (kg) | number | Yes | The weight of the shipment unit in kilograms. Must be a positive number and greater than 0.10 and less than 99. | +| shipmentUnitReference | Shipment unit reference | string | No | The reference for the shipment unit. Max length is 40 characters. | +| partnerParcelNumber | Partner parcel number | string | No | The partner parcel number for the shipment unit. Max length is 50 characters. | +| note1 | Note 1 | string | No | Note 1 for the shipment unit. Max length is 50 characters. | +| note2 | Note 2 | string | No | Note 2 for the shipment unit. Max length is 50 characters. | +| shipmentUnitService | Shipment unit service | [GLS_SHIPMENT_UNIT_SERVICE](./types.mdx#gls_shipment_unit_service) | Yes | The service associated with the shipment unit. | + +Return Type: [GLS_SHIPMENT_UNIT](./types.mdx#gls_shipment_unit) + +# + Creates a GLS shipment unit (an individual parcel within a shipment). Date: Thu, 2 Apr 2026 16:35:54 +0200 Subject: [PATCH 13/17] Fix GLS shipment unit service link --- actions/gls-action/scripts/generateDocs.ts | 4 ++-- docs/Actions/GLS/functions.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/actions/gls-action/scripts/generateDocs.ts b/actions/gls-action/scripts/generateDocs.ts index 85e3eff..8d14952 100644 --- a/actions/gls-action/scripts/generateDocs.ts +++ b/actions/gls-action/scripts/generateDocs.ts @@ -292,8 +292,8 @@ async function generateFunctions(sdk: ActionSdk): Promise { function getLinkFromType(typeName?: string) { if (!typeName || !typeName.startsWith("GLS_")) return typeName switch (typeName) { // Some edge cases - case "SHIPMENT_UNIT_SERVICE": { - typeName = "SHIPMENT_UNIT$Service" + case "GLS_SHIPMENT_UNIT_SERVICE": { + typeName = "GLS_SHIPMENT_UNIT$Service" break } } diff --git a/docs/Actions/GLS/functions.mdx b/docs/Actions/GLS/functions.mdx index 0da0969..0e8cd7c 100644 --- a/docs/Actions/GLS/functions.mdx +++ b/docs/Actions/GLS/functions.mdx @@ -22,7 +22,7 @@ The GLS Action exposes 26 functions grouped into three categories: | partnerParcelNumber | Partner parcel number | string | No | The partner parcel number for the shipment unit. Max length is 50 characters. | | note1 | Note 1 | string | No | Note 1 for the shipment unit. Max length is 50 characters. | | note2 | Note 2 | string | No | Note 2 for the shipment unit. Max length is 50 characters. | -| shipmentUnitService | Shipment unit service | [GLS_SHIPMENT_UNIT_SERVICE](./types.mdx#gls_shipment_unit_service) | Yes | The service associated with the shipment unit. | +| shipmentUnitService | Shipment unit service | [GLS_SHIPMENT_UNIT$Service](./types.mdx#gls_shipment_unitservice) | Yes | The service associated with the shipment unit. | Return Type: [GLS_SHIPMENT_UNIT](./types.mdx#gls_shipment_unit) From 5618dc5b734c1eb1b327c28b68b98d3d680a394c Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Thu, 2 Apr 2026 16:51:29 +0200 Subject: [PATCH 14/17] Fix regex pattern in documentation generation for parameter matching --- actions/gls-action/scripts/generateDocs.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/actions/gls-action/scripts/generateDocs.ts b/actions/gls-action/scripts/generateDocs.ts index 8d14952..4b41db7 100644 --- a/actions/gls-action/scripts/generateDocs.ts +++ b/actions/gls-action/scripts/generateDocs.ts @@ -267,7 +267,7 @@ async function generateFunctions(sdk: ActionSdk): Promise { const trimmed = param.trim(); // Match: name?: type OR name: type - const match = trimmed.match(new RegExp(`${paramName}\s*(\\?)?\\s*:\\s*(.+)`)); + const match = trimmed.match(new RegExp(`${paramName}\\s*(\\?)?\\s*:\\s*(.+)`)); if (match) { const isOptional = match[1] === "?"; const type = match[2].trim(); @@ -393,7 +393,7 @@ All shipment functions accept a common set of parameters in addition to their ty const headers = ["Parameter", "Name", "Type", "Required", "Description"] - let rows = [] + const rows = [] definition.parameters.forEach(param => { const paramInfo = getParamInfo(definition.signature, param.runtimeName); From bee73bb4ec6f5bcf089e56a396cd0af03478ff16 Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Thu, 2 Apr 2026 20:34:03 +0200 Subject: [PATCH 15/17] Make docs generator abstract --- actions/gls-action/scripts/generateDocs.ts | 466 ++----------------- docs/Actions/GLS/functions.mdx | 169 +++---- docs/Actions/GLS/types.mdx | 505 ++++++++++----------- src/standardActionDocs.ts | 399 ++++++++++++++++ tsconfig.base.json | 2 +- 5 files changed, 776 insertions(+), 765 deletions(-) create mode 100644 src/standardActionDocs.ts diff --git a/actions/gls-action/scripts/generateDocs.ts b/actions/gls-action/scripts/generateDocs.ts index 4b41db7..27f8ffb 100644 --- a/actions/gls-action/scripts/generateDocs.ts +++ b/actions/gls-action/scripts/generateDocs.ts @@ -1,357 +1,39 @@ +import {runStandardActionDocs, StandardActionDocsConfig} from "../../../src/standardActionDocs" import {loadAllDefinitions} from "../src/helpers"; -import { - ActionSdk, - HerculesActionConfigurationDefinition, - HerculesDataType, HerculesFlowType, HerculesRegisterFunctionParameter, -} from "@code0-tech/hercules"; -import {Project, SymbolFlags, Type} from "ts-morph"; -import {writeFileSync} from "fs" - -const state = { - dataTypes: [] as HerculesDataType[], - actionConfigurationDefinitions: [] as HerculesActionConfigurationDefinition[], - runtimeFunctions: [] as HerculesRegisterFunctionParameter[], - flowTypes: [] as HerculesFlowType[] -} - - -async function run(): Promise { - const sdk = { - 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() +export function createGlsDocsConfig(): StandardActionDocsConfig { + return { + actionName: "GLS", + typePrefix: "GLS_", + typesOutputPath: "../../docs/Actions/GLS/types.mdx", + functionsOutputPath: "../../docs/Actions/GLS/functions.mdx", + loadAllDefinitions, + typeLinkOverrides: { + GLS_SHIPMENT_UNIT_SERVICE: "GLS_SHIPMENT_UNIT$Service", }, - registerFunctionDefinitions: (...functionDefinitions) => { - state.runtimeFunctions = [ - ...functionDefinitions, - ...state.runtimeFunctions - ] - return Promise.resolve() + typesCopy: { + title: "Datatypes", + description: "All data types registered by the GLS Action.", + heading: "GLS Action Types", + intro: `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.`, }, - registerFlowTypes: (...flowTypes) => { - state.flowTypes = [ - ...state.flowTypes, - ...flowTypes - ] - return Promise.resolve() - } - - }; - await loadAllDefinitions(sdk) - - return sdk -} - - -function generateDatatypes(): string { - let generatedDoc = "" - - generatedDoc += `--- -title: Datatypes -description: All data types registered by the GLS Action. ---- -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 { - const map: Record = {}; - - 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() - } - let globalDocumentation: string - - 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 => { - if (info.getName() === "global") { - globalDocumentation = (globalDocumentation || "") + "\n" + part.text.trim() - return - } - 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 = `` - generatedDoc += ` -# ${key}${globalDocumentation || "\nNo documentation provided for this type."} - -${table} - ` - } - }) - return generatedDoc -} - -interface Translation { - code?: string; - content?: string; -} - -interface FunctionDefinition { - descriptions?: Array; - displayMessages?: Array; - identifier?: string; - names?: Array; - parameterDefinitions?: { - nodes: { - identifier: string, - descriptions: Array, - names: Array - }[] - }; -} - -async function generateFunctions(sdk: ActionSdk): Promise { - function getParamInfo(signature: string, paramName: string): { optional: boolean; type: string | null } { - const paramsMatch = signature.match(/\((.*)\)/s); - if (!paramsMatch) { - return {optional: false, type: null}; - } - - const params = paramsMatch[1].split(","); - - for (const param of params) { - const trimmed = param.trim(); - - // Match: name?: type OR name: type - const match = trimmed.match(new RegExp(`${paramName}\\s*(\\?)?\\s*:\\s*(.+)`)); - if (match) { - const isOptional = match[1] === "?"; - const type = match[2].trim(); - - return { - optional: isOptional, - type - }; - } - } - - return {optional: false, type: null}; - } - - function generateMarkdownTable(headers: string[], rows: string[][]) { - const headerRow = `| ${headers.join(' | ')} |`; - const separator = `| ${headers.map(() => '---').join(' | ')} |`; - const bodyRows = rows.map(row => `| ${row.join(' | ')} |`); - - return [headerRow, separator, ...bodyRows].join('\n'); - } - function getLinkFromType(typeName?: string) { - if (!typeName || !typeName.startsWith("GLS_")) return typeName - switch (typeName) { // Some edge cases - case "GLS_SHIPMENT_UNIT_SERVICE": { - typeName = "GLS_SHIPMENT_UNIT$Service" - break - } - } - const normalizedName = typeName.toLowerCase() - .replace(/-/g, "_") - .replace(/\$/g, ""); - return `[${typeName}](./types.mdx#${normalizedName})` - } - - async function loadFunctions(modules: Record Promise>) { - for (const path in modules) { - - const mod: any = await modules[path](); - if (typeof mod.default === 'function') { - try { - await mod.default(sdk); - } catch (error) { - console.log(`Error registering functions from ${path}:`, error); - } - } - } - } - - let generatedDoc = `--- -title: Functions -description: All functions registered by the GLS Action. ---- - -The GLS Action exposes ${state.runtimeFunctions.length} functions grouped into three categories: + functionsCopy: { + title: "Functions", + description: "All functions registered by the GLS Action.", + intro: `The GLS Action exposes functions grouped into three categories: - **Builder functions** — Construct data objects (no API call) - **Shipment functions** — Create different types of GLS shipments (calls GLS API) -- **API functions** — Query or modify shipments (calls GLS API) - ---- -` - const functionGlobs = [ - import.meta.glob('../src/functions/utils/*.ts'), - import.meta.glob('../src/functions/services/*.ts'), - import.meta.glob('../src/functions/*.ts') - ] - for (let i = 0; i < functionGlobs.length; i++) { - const modules = functionGlobs[i] - state.runtimeFunctions = [] - await loadFunctions(modules) - - switch (i) { - case 0: { - generatedDoc += ` -## Builder functions - ` - break - } - case 1: { - generatedDoc += ` -## Shipment functions - -All shipment functions accept a common set of parameters in addition to their type-specific parameters. They call the GLS ShipIT API (\`POST /rs/shipments\`) and return a \`GLS_CREATE_PARCELS_RESPONSE\`. +- **API functions** — Query or modify shipments (calls GLS API)`, + }, + functionGroups: [ + { + heading: "Builder functions", + modules: import.meta.glob("../src/functions/utils/*.ts"), + }, + { + heading: "Shipment functions", + intro: `All shipment functions accept a common set of parameters in addition to their type-specific parameters. They call the GLS ShipIT API (\`POST /rs/shipments\`) and return a \`GLS_CREATE_PARCELS_RESPONSE\`. **Common parameters for all shipment functions:** @@ -362,87 +44,15 @@ All shipment functions accept a common set of parameters in addition to their ty | \`returnOptions\` | GLS_RETURN_OPTIONS | No | Whether to return print data and routing info | | \`customContent\` | GLS_CUSTOM_CONTENT | No | Custom logo and barcode settings | ---- - ` - break - } - default: { - generatedDoc += ` - ## API functions - ` - } - } - - state.runtimeFunctions.forEach(value => { - const definition = value.definition; - const generateDefinition: FunctionDefinition = { - descriptions: definition.description, - names: definition.name, - identifier: definition.runtimeName, - parameterDefinitions: { - nodes: definition.parameters.map(p => { - return { - names: p.name, - identifier: p.runtimeName, - descriptions: p.description - } - }) - }, - displayMessages: definition.displayMessage - } - - const headers = ["Parameter", "Name", "Type", "Required", "Description"] - - const rows = [] - - definition.parameters.forEach(param => { - const paramInfo = getParamInfo(definition.signature, param.runtimeName); - - paramInfo.type = getLinkFromType(paramInfo.type); - - rows.push([ - param.runtimeName, - param.name[0].content, - paramInfo.type?.replace(/\|/g, "\\|") || "Unknown", - paramInfo.optional ? "No" : "Yes", - param.description[0].content - ]) - }) - - generatedDoc += ` -### \`${definition.runtimeName}\` - -${generateMarkdownTable(headers, rows)} - -Return Type: ${getLinkFromType(definition.signature.split("):")[1].trim())} - -# - -${definition.documentation?.at(0).content || ""} - - - ---- -` - }) +---`, + modules: import.meta.glob("../src/functions/services/*.ts"), + }, + { + heading: "API functions", + modules: import.meta.glob("../src/functions/*.ts"), + }, + ], } - - - return generatedDoc } -run().then(async (sdk) => { - writeFileSync( - "../../docs/Actions/GLS/types.mdx", - generateDatatypes(), - "utf8" - ) - - writeFileSync( - "../../docs/Actions/GLS/functions.mdx", - await generateFunctions(sdk), - "utf-8" - ) -}) +await runStandardActionDocs(createGlsDocsConfig()) diff --git a/docs/Actions/GLS/functions.mdx b/docs/Actions/GLS/functions.mdx index 0e8cd7c..798ed9f 100644 --- a/docs/Actions/GLS/functions.mdx +++ b/docs/Actions/GLS/functions.mdx @@ -3,7 +3,7 @@ title: Functions description: All functions registered by the GLS Action. --- -The GLS Action exposes 26 functions grouped into three categories: +The GLS Action exposes functions grouped into three categories: - **Builder functions** — Construct data objects (no API call) - **Shipment functions** — Create different types of GLS shipments (calls GLS API) @@ -12,7 +12,8 @@ The GLS Action exposes 26 functions grouped into three categories: --- ## Builder functions - + + ### `createShipmentUnit` | Parameter | Name | Type | Required | Description | @@ -29,7 +30,7 @@ Return Type: [GLS_SHIPMENT_UNIT](./types.mdx#gls_shipment_unit) # Creates a GLS shipment unit (an individual parcel within a shipment). - + - +} /> + --- ### `createPrintingOptions` @@ -161,7 +162,7 @@ Return Type: [GLS_PRINTING_OPTIONS](./types.mdx#gls_printing_options) # Creates GLS printing options that control how labels are generated. - + - +} /> + --- ### `createCustomContent` @@ -222,7 +223,7 @@ Return Type: [GLS_CUSTOM_CONTENT](./types.mdx#gls_custom_content) # Creates custom content settings for GLS labels, including logos and barcodes. - + - +} /> + --- ### `createConsignee` @@ -342,7 +343,7 @@ Return Type: [GLS_CONSIGNEE](./types.mdx#gls_consignee) # Creates a GLS consignee (recipient) object for use in shipments. - + - +} /> + --- ### `createAddress` @@ -456,7 +457,7 @@ Return Type: [GLS_ADDRESS](./types.mdx#gls_address) # Creates a GLS address object (`GLS_ADDRESS`) for use in shipments as consignee, shipper, or return address. - + - +} /> + --- ## Shipment functions @@ -696,7 +697,8 @@ All shipment functions accept a common set of parameters in addition to their ty | `customContent` | GLS_CUSTOM_CONTENT | No | Custom logo and barcode settings | --- - + + ### `createTyreShipment` | Parameter | Name | Type | Required | Description | @@ -711,7 +713,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Creates a shipment specifically for tyre/wheel delivery (uses the GLS TyreService). - + - +} /> + --- ### `createSignatureShipment` @@ -816,7 +818,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Creates a shipment that requires a recipient signature upon delivery. - + - +} /> + --- ### `createShopReturnShipment` @@ -923,7 +925,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Creates a return shipment from a GLS Parcel Shop (customer drops off parcel at a shop). - + - +} /> + --- ### `createShopDeliveryShipment` @@ -1059,7 +1061,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Delivers a parcel to a GLS Parcel Shop where the recipient can collect it. - + - +} /> + --- ### `createPickAndShipShipment` @@ -1180,7 +1182,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Schedules a pickup from the consignee's address on a given date. - + - +} /> + --- ### `createIdentShipment` @@ -1304,7 +1306,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Delivers a parcel with identity verification - the driver checks the recipient's ID document. - + - +} /> + --- ### `createIdentPinShipment` @@ -1471,7 +1473,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Delivers a parcel with PIN and optional birthdate verification. - + - +} /> + --- ### `createGuaranteed24Shipment` @@ -1606,7 +1608,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Creates a shipment with guaranteed delivery within 24 hours. - + - +} /> + --- ### `createFlexDeliveryShipment` @@ -1711,7 +1713,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Creates a shipment with flexible delivery - the recipient can redirect or reschedule delivery. - + - +} /> + --- ### `createExchangeShipment` @@ -1818,7 +1820,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Delivers a new parcel while simultaneously picking up an existing one (exchange). - + - +} /> + --- ### `createDepositShipment` @@ -1954,7 +1956,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Delivers a parcel to a designated deposit location (e.g. a garage or shed) without requiring a signature. - + - +} /> + --- ### `createDeliverySaturdayShipment` @@ -2074,7 +2076,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Creates an EXPRESS shipment for Saturday delivery. - + - +} /> + --- ### `createDeliveryNextWorkingDayShipment` @@ -2179,7 +2181,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Creates an EXPRESS shipment for delivery on the next working day (EOB service). - + - +} /> + --- ### `createDeliveryAtWorkShipment` @@ -2290,7 +2292,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Delivers a parcel to a specific location within a workplace (building, floor, room). - + - +} /> + --- ### `createAddresseeOnlyShipment` @@ -2485,7 +2487,7 @@ Return Type: [GLS_CREATE_PARCELS_RESPONSE](./types.mdx#gls_create_parcels_respon # Creates a shipment that can only be delivered to the named addressee (no neighbor delivery). - + - +} /> + --- - ## API functions - +## API functions + + ### `validateShipment` | Parameter | Name | Type | Required | Description | @@ -2589,7 +2592,7 @@ Return Type: [GLS_VALIDATE_SHIPMENT_RESPONSE_DATA](./types.mdx#gls_validate_ship # Validates a shipment against the GLS API without creating it. Use this before `createShipment` functions to catch errors early. - + - +} /> + --- ### `updateParcelWeight` @@ -2646,7 +2649,7 @@ Return Type: [GLS_END_OF_DAY_RESPONSE_DATA](./types.mdx#gls_end_of_day_response_ # Updates the weight of an already-created parcel. Useful when the final weight is only known after packaging. - + - +} /> + --- ### `reprintParcel` @@ -2703,7 +2706,7 @@ Return Type: [GLS_REPRINT_PARCEL_RESPONSE_DATA](./types.mdx#gls_reprint_parcel_r # Reprints the label for an existing parcel. Use this if the original label is damaged, lost, or needs to be printed in a different format. - + - +} /> + --- ### `getEndOfDayReport` @@ -2760,7 +2763,7 @@ Return Type: [GLS_END_OF_DAY_RESPONSE_DATA](./types.mdx#gls_end_of_day_response_ # Retrieves all shipments dispatched on a given date. Useful for reconciliation and end-of-day processing. - + - +} /> + --- ### `getAllowedServices` @@ -2817,7 +2820,7 @@ Return Type: [GLS_ALLOWED_SERVICES_RESPONSE_DATA](./types.mdx#gls_allowed_servic # Returns the GLS services available for a given origin/destination country and ZIP code combination. - + - +} /> + --- ### `cancelShipment` @@ -2874,7 +2877,7 @@ Return Type: [GLS_CANCEL_SHIPMENT_RESPONSE_DATA](./types.mdx#gls_cancel_shipment # Cancels an existing shipment by its Track ID. Only possible if the parcel has not yet been scanned. - + - +} /> + --- diff --git a/docs/Actions/GLS/types.mdx b/docs/Actions/GLS/types.mdx index 8188311..29e7376 100644 --- a/docs/Actions/GLS/types.mdx +++ b/docs/Actions/GLS/types.mdx @@ -6,21 +6,20 @@ 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. +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. + +--- ---- - # GLS_VALIDATE_SHIPMENT_REQUEST_DATA No documentation provided for this type. @@ -29,18 +28,18 @@ typeDescriptionLink: '#gls_shipment', No documentation provided for this type. @@ -49,12 +48,12 @@ typeDescriptionLink: '#gls_validate_shipment_response_datavalidationresult', No documentation provided for this type. @@ -63,23 +62,23 @@ typeDescriptionLink: '#gls_validate_shipment_response_datavalidationresultissues No documentation provided for this type. @@ -88,41 +87,41 @@ No documentation provided for this type. No documentation provided for this type. @@ -131,11 +130,11 @@ No documentation provided for this type. No documentation provided for this type. @@ -144,40 +143,40 @@ No documentation provided for this type. No documentation provided for this type. @@ -186,11 +185,11 @@ typeDescriptionLink: '#gls_unit_servicelimitedquantities', No documentation provided for this type. @@ -199,19 +198,19 @@ No documentation provided for this type. No documentation provided for this type. # GLS_UNIT_SERVICE$HazardousGoods No documentation provided for this type. @@ -220,17 +219,17 @@ typeDescriptionLink: '#gls_unit_servicehazardousgoodsharzardousgood', No documentation provided for this type. @@ -239,23 +238,23 @@ No documentation provided for this type. No documentation provided for this type. @@ -264,23 +263,23 @@ No documentation provided for this type. No documentation provided for this type. @@ -289,19 +288,19 @@ No documentation provided for this type. No documentation provided for this type. @@ -310,42 +309,42 @@ typeDescriptionLink: '#gls_address', No documentation provided for this type. @@ -354,40 +353,40 @@ typeDescriptionLink: '#gls_shipment_unitservice', No documentation provided for this type. @@ -396,11 +395,11 @@ typeDescriptionLink: '#gls_shipment_unitservicelimitedquantities', No documentation provided for this type. @@ -409,19 +408,19 @@ No documentation provided for this type. No documentation provided for this type. # GLS_SHIPMENT_UNIT$Service$HazardousGoods No documentation provided for this type. @@ -430,17 +429,17 @@ typeDescriptionLink: '#gls_shipment_unitservicehazardousgoodsharzardousgood', No documentation provided for this type. @@ -449,23 +448,23 @@ No documentation provided for this type. No documentation provided for this type. @@ -474,23 +473,23 @@ No documentation provided for this type. No documentation provided for this type. @@ -499,82 +498,82 @@ No documentation provided for this type. No documentation provided for this type. @@ -583,12 +582,12 @@ typeDescriptionLink: '#gls_shipmentreturn', No documentation provided for this type. @@ -597,75 +596,75 @@ typeDescriptionLink: '#gls_address', No documentation provided for this type. @@ -674,12 +673,12 @@ typeDescriptionLink: '#gls_shipment_without_servicesreturn', No documentation provided for this type. @@ -688,17 +687,17 @@ typeDescriptionLink: '#gls_address', No documentation provided for this type. @@ -707,48 +706,48 @@ No documentation provided for this type. No documentation provided for this type. @@ -757,12 +756,12 @@ typeDescriptionLink: '#gls_reprint_parcel_request_dataprintingoptions', No documentation provided for this type. @@ -771,17 +770,17 @@ typeDescriptionLink: '#gls_reprint_parcel_request_dataprintingoptionsreturnlabel No documentation provided for this type. @@ -790,12 +789,12 @@ No documentation provided for this type. No documentation provided for this type. @@ -804,37 +803,37 @@ typeDescriptionLink: '#gls_reprint_parcel_response_datacreatedshipment', No documentation provided for this type. @@ -843,17 +842,17 @@ typeDescriptionLink: '#gls_reprint_parcel_response_datacreatedshipmentprintdata' No documentation provided for this type. @@ -862,37 +861,37 @@ No documentation provided for this type. No documentation provided for this type. @@ -901,35 +900,35 @@ typeDescriptionLink: '#gls_reprint_parcel_response_datacreatedshipmentparceldata No documentation provided for this type. @@ -938,29 +937,29 @@ No documentation provided for this type. No documentation provided for this type. @@ -969,25 +968,25 @@ No documentation provided for this type. No documentation provided for this type. @@ -996,17 +995,17 @@ typeDescriptionLink: '#gls_printing_optionsdefineprinter', No documentation provided for this type. @@ -1015,17 +1014,17 @@ No documentation provided for this type. No documentation provided for this type. @@ -1034,11 +1033,11 @@ No documentation provided for this type. No documentation provided for this type. @@ -1047,12 +1046,12 @@ No documentation provided for this type. No documentation provided for this type. @@ -1061,38 +1060,38 @@ typeDescriptionLink: '#gls_end_of_day_response_datashipments', No documentation provided for this type. @@ -1101,23 +1100,23 @@ typeDescriptionLink: '#gls_end_of_day_response_datashipmentsshipmentunit', No documentation provided for this type. @@ -1126,18 +1125,18 @@ No documentation provided for this type. No documentation provided for this type. @@ -1146,12 +1145,12 @@ typeDescriptionLink: '#gls_address', No documentation provided for this type. @@ -1160,35 +1159,35 @@ typeDescriptionLink: '#gls_address', No documentation provided for this type. @@ -1197,12 +1196,12 @@ No documentation provided for this type. No documentation provided for this type. @@ -1211,43 +1210,43 @@ typeDescriptionLink: '#gls_create_parcels_responsecreatedshipment', No documentation provided for this type. @@ -1256,17 +1255,17 @@ typeDescriptionLink: '#gls_create_parcels_responsecreatedshipmentprintdata', No documentation provided for this type. @@ -1275,31 +1274,31 @@ No documentation provided for this type. No documentation provided for this type. @@ -1308,35 +1307,35 @@ typeDescriptionLink: '#gls_create_parcels_responsecreatedshipmentparceldatarouti No documentation provided for this type. @@ -1345,29 +1344,29 @@ No documentation provided for this type. No documentation provided for this type. @@ -1376,30 +1375,30 @@ No documentation provided for this type. No documentation provided for this type. @@ -1408,11 +1407,11 @@ typeDescriptionLink: '#gls_address', No documentation provided for this type. @@ -1421,17 +1420,17 @@ No documentation provided for this type. No documentation provided for this type. @@ -1440,25 +1439,25 @@ No documentation provided for this type. No documentation provided for this type. @@ -1467,17 +1466,17 @@ typeDescriptionLink: '#gls_allowed_services_request_datadestination', No documentation provided for this type. @@ -1486,17 +1485,17 @@ No documentation provided for this type. No documentation provided for this type. @@ -1505,12 +1504,12 @@ No documentation provided for this type. No documentation provided for this type. @@ -1519,17 +1518,17 @@ typeDescriptionLink: '#gls_allowed_services_response_dataallowedservices', No documentation provided for this type. @@ -1538,83 +1537,83 @@ No documentation provided for this type. No documentation provided for this type. diff --git a/src/standardActionDocs.ts b/src/standardActionDocs.ts new file mode 100644 index 0000000..5d3b9ab --- /dev/null +++ b/src/standardActionDocs.ts @@ -0,0 +1,399 @@ +import {writeFileSync} from "fs" +import { + ActionSdk, + HerculesActionConfigurationDefinition, + HerculesDataType, + HerculesFlowType, + HerculesRegisterFunctionParameter, +} from "@code0-tech/hercules" +import {Project, SymbolFlags, Type} from "ts-morph" + +interface Translation { + code?: string + content?: string +} + +interface FunctionDefinitionCard { + descriptions?: Array + displayMessages?: Array + identifier?: string + names?: Array + parameterDefinitions?: { + nodes: { + identifier: string + descriptions: Array + names: Array + }[] + } +} + +interface RegistryState { + dataTypes: HerculesDataType[] + actionConfigurationDefinitions: HerculesActionConfigurationDefinition[] + runtimeFunctions: HerculesRegisterFunctionParameter[] + flowTypes: HerculesFlowType[] +} + +interface FunctionGroup { + heading: string + modules: Record Promise> + intro?: string +} + +interface TypesCopy { + title: string + description: string + heading: string + intro: string +} + +interface FunctionsCopy { + title: string + description: string + intro: string +} + +export interface StandardActionDocsConfig { + actionName: string + typePrefix: string + typesOutputPath: string + functionsOutputPath: string + typesCopy: TypesCopy + functionsCopy: FunctionsCopy + functionGroups: FunctionGroup[] + typeLinkOverrides?: Record + loadAllDefinitions: (sdk: ActionSdk) => Promise +} + +function createRegistry(): RegistryState { + return { + dataTypes: [], + actionConfigurationDefinitions: [], + runtimeFunctions: [], + flowTypes: [], + } +} + +function createMockSdk(registry: RegistryState): ActionSdk { + return { + onError: () => {}, + connect: () => Promise.resolve([]), + dispatchEvent: () => Promise.resolve(), + getProjectActionConfigurations: () => [], + config: { + authToken: "", + aquilaUrl: "", + version: "", + actionId: "", + }, + fullyConnected: () => false, + registerDataTypes: (...dataTypes) => { + registry.dataTypes = [...dataTypes, ...registry.dataTypes] + return Promise.resolve() + }, + registerConfigDefinitions: (...actionConfigurations) => { + registry.actionConfigurationDefinitions = [ + ...actionConfigurations, + ...registry.actionConfigurationDefinitions, + ] + return Promise.resolve() + }, + registerFunctionDefinitions: (...functionDefinitions) => { + registry.runtimeFunctions = [...functionDefinitions, ...registry.runtimeFunctions] + return Promise.resolve() + }, + registerFlowTypes: (...flowTypes) => { + registry.flowTypes = [...registry.flowTypes, ...flowTypes] + return Promise.resolve() + }, + } +} + +function breakDownType(typeName: string, code: string): Record { + const map: Record = {} + 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 lines: string[] = [] + + type.getProperties().forEach(symbol => { + const name = symbol.getName() + const decl = symbol.getDeclarations()[0] + if (!decl) { + return + } + + let propType = symbol.getTypeAtLocation(decl) + let isArray = false + if (propType.isArray()) { + propType = propType.getArrayElementTypeOrThrow() + isArray = true + } + + let typeText: string + if (propType.getText().startsWith("{")) { + const nestedName = `${currentName}$${name}` + const nestedType = buildType(propType, nestedName) + map[nestedName] = `export type ${nestedName} = ${nestedType};` + typeText = isArray ? `${nestedName}[]` : nestedName + } else { + typeText = propType.getText(decl) + } + + const jsDocs = (decl as any).getJsDocs?.() + ?.map((doc: any) => doc.getText()) + .join("\n") + const docPrefix = jsDocs ? `${jsDocs}\n` : "" + lines.push(`${docPrefix}${name}${symbol.hasFlags(SymbolFlags.Optional) ? "?" : ""}: ${typeText};`) + }) + + return `{\n${lines.map(line => ` ${line}`).join("\n")}\n}` + } + + const finalType = buildType(rootType, typeName) + map[typeName] = `export type ${typeName} = ${finalType};` + return map +} + +function normalizeAnchor(typeName: string): string { + return typeName.toLowerCase().replace(/-/g, "_").replace(/\$/g, "").replace("[]", "") +} + +function getTypeLink(typeName: string | null, config: StandardActionDocsConfig): string | null { + if (!typeName) { + return null + } + + const override = config.typeLinkOverrides?.[typeName] + const resolved = override || typeName + + if (!resolved.startsWith(config.typePrefix)) { + return resolved + } + + return `[${resolved}](./types.mdx#${normalizeAnchor(resolved)})` +} + +function generateDatatypes(config: StandardActionDocsConfig, registry: RegistryState): string { + let generatedDoc = `--- +title: ${config.typesCopy.title} +description: ${config.typesCopy.description} +--- +import {TypeTable} from "fumadocs-ui/components/type-table"; + +# ${config.typesCopy.heading} + +${config.typesCopy.intro} + +--- +` + + registry.dataTypes.forEach(value => { + value.type = `export type ${value.identifier} = ${value.type}`.replace(/ \| undefined/g, "") + + const parts = breakDownType(value.identifier, value.type) + const entries = Object.entries(parts).reverse() + + entries.forEach(([key, rawType]) => { + let typeString = "\n" + let globalDocumentation = "" + + const project = new Project({useInMemoryFileSystem: true}) + const sourceFile = project.createSourceFile("example.ts", rawType) + const typeAlias = sourceFile.getTypeAliasOrThrow(key) + + let parsedType = typeAlias.getType() + if (parsedType.isArray()) { + parsedType = parsedType.getArrayElementTypeOrThrow() + } + + parsedType.getProperties().forEach(property => { + const propertyType = property.getTypeAtLocation(typeAlias) + const propertyTypeText = propertyType.getText() + + const docs: Record = { + description: "No description set", + deprecated: false, + default: undefined, + link: undefined, + } + + property.getJsDocTags().forEach(tag => { + tag.getText().forEach(part => { + if (tag.getName() === "global") { + globalDocumentation = `${globalDocumentation}\n${part.text.trim()}` + return + } + docs[tag.getName()] = part.text.trim() + }) + }) + + if (propertyTypeText.startsWith(config.typePrefix)) { + docs.link = normalizeAnchor(propertyTypeText) + } + + typeString += `${property.getName()}: { + description: '${docs.description}', + deprecated: ${docs.deprecated}, + required: ${!property.isOptional()}, ${docs.link ? `\ntypeDescriptionLink: '#${docs.link}',` : ""} + type: '${propertyTypeText}', ${docs.default ? `\ndefault: ${docs.default}` : ""} + }, + ` + }) + + generatedDoc += ` +# ${key}${globalDocumentation || "\nNo documentation provided for this type."} + + + ` + }) + }) + + return generatedDoc +} + +function getParamInfo(signature: string, paramName: string): { optional: boolean; type: string | null } { + const paramsMatch = signature.match(/\((.*)\)/s) + if (!paramsMatch) { + return {optional: false, type: null} + } + + const params = paramsMatch[1].split(",") + for (const param of params) { + const trimmed = param.trim() + const match = trimmed.match(new RegExp(`${paramName}\\s*(\\?)?\\s*:\\s*(.+)`)) + if (match) { + return { + optional: match[1] === "?", + type: match[2].trim(), + } + } + } + + return {optional: false, type: null} +} + +function generateMarkdownTable(headers: string[], rows: string[][]): string { + const headerRow = `| ${headers.join(" | ")} |` + const separator = `| ${headers.map(() => "---").join(" | ")} |` + const bodyRows = rows.map(row => `| ${row.join(" | ")} |`) + return [headerRow, separator, ...bodyRows].join("\n") +} + +async function loadFunctions( + modules: Record Promise>, + sdk: ActionSdk, + registry: RegistryState, +): Promise { + for (const path in modules) { + const mod: any = await modules[path]() + if (typeof mod.default !== "function") { + continue + } + + try { + await mod.default(sdk) + } catch (error) { + console.log(`Error registering functions from ${path}:`, error) + } + } + + registry.runtimeFunctions = [...registry.runtimeFunctions] +} + +async function generateFunctions(config: StandardActionDocsConfig, sdk: ActionSdk, registry: RegistryState): Promise { + let generatedDoc = `--- +title: ${config.functionsCopy.title} +description: ${config.functionsCopy.description} +--- + +${config.functionsCopy.intro} + +--- +` + + for (const group of config.functionGroups) { + registry.runtimeFunctions = [] + await loadFunctions(group.modules, sdk, registry) + + generatedDoc += ` +## ${group.heading} +${group.intro ? `\n${group.intro}\n` : ""} +` + + registry.runtimeFunctions.forEach(value => { + const definition = value.definition + const card: FunctionDefinitionCard = { + descriptions: definition.description, + names: definition.name, + identifier: definition.runtimeName, + parameterDefinitions: { + nodes: definition.parameters.map(parameter => ({ + names: parameter.name, + identifier: parameter.runtimeName, + descriptions: parameter.description, + })), + }, + displayMessages: definition.displayMessage, + } + + const headers = ["Parameter", "Name", "Type", "Required", "Description"] + const rows: string[][] = definition.parameters.map(parameter => { + const paramInfo = getParamInfo(definition.signature, parameter.runtimeName) + const linkedType = getTypeLink(paramInfo.type, config) + + return [ + parameter.runtimeName, + parameter.name[0].content, + linkedType?.replace(/\|/g, "\\|") || "Unknown", + paramInfo.optional ? "No" : "Yes", + parameter.description[0].content, + ] + }) + + const returnType = definition.signature.split("):")[1]?.trim() + generatedDoc += ` +### \`${definition.runtimeName}\` + +${generateMarkdownTable(headers, rows)} + +Return Type: ${getTypeLink(returnType || null, config) || "Unknown"} + +# + +${definition.documentation?.at(0)?.content || ""} + + + +--- +` + }) + } + + return generatedDoc +} + +export async function runStandardActionDocs(config: StandardActionDocsConfig): Promise { + const registry = createRegistry() + const sdk = createMockSdk(registry) + + await config.loadAllDefinitions(sdk) + + const typesContent = generateDatatypes(config, registry) + const functionsContent = await generateFunctions(config, sdk, registry) + + writeFileSync(config.typesOutputPath, typesContent, "utf8") + writeFileSync(config.functionsOutputPath, functionsContent, "utf8") +} + diff --git a/tsconfig.base.json b/tsconfig.base.json index 3363612..e8bddc1 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -9,6 +9,6 @@ "skipLibCheck": true, "types": ["vite/client"], }, - "include": ["src/**/*"], + "include": ["src/**/*", "scripts"], "exclude": ["node_modules", "dist", "***/test/**", "**/*.test.ts"] } \ No newline at end of file From 7e16c507bedca7c826f39d8228eb4e8c95b9ad67 Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Thu, 9 Apr 2026 20:38:14 +0200 Subject: [PATCH 16/17] Refactor printing options schema to separate return labels and enhance type definitions --- .../src/types/glsPrintingOptions.ts | 45 ++++++++++++++----- package-lock.json | 25 ++++++----- 2 files changed, 48 insertions(+), 22 deletions(-) diff --git a/actions/gls-action/src/types/glsPrintingOptions.ts b/actions/gls-action/src/types/glsPrintingOptions.ts index 1abd541..9d59be3 100644 --- a/actions/gls-action/src/types/glsPrintingOptions.ts +++ b/actions/gls-action/src/types/glsPrintingOptions.ts @@ -1,14 +1,16 @@ import {ActionSdk} from "@code0-tech/hercules"; -import {singleZodSchemaToTypescriptDef} from "../helpers"; +import {singleZodSchemaToTypescriptDef, zodSchemaToTypescriptDefs} from "../helpers"; import {z} from "zod"; +export const ReturnLabelsSchema = z.object({ + TemplateSet: z.enum([ + "NONE", "D_200", "PF_4_I", "PF_4_I_200", "PF_4_I_300", "PF_8_D_200", "T_200_BF", "T_300_BF", "ZPL_200", "ZPL_200_TRACKID_EAN_128", "ZPL_200_TRACKID_CODE_39", "ZPL_200_REFNO_EAN_128", "ZPL_200_REFNO_CODE_39", "ZPL_300", "ZPL_300_TRACKID_EAN_128", "ZPL_300_TRACKID_CODE_39", "ZPL_300_REFNO_EAN_128", "ZPL_300_REFNO_CODE_39" + ]), + LabelFormat: z.enum(["PDF", "ZEBRA", "INTERMEC", "DATAMAX", "TOSHIBA", "PNG"]) +}) + export const PrintingOptionsSchema = z.object({ - ReturnLabels: z.object({ - TemplateSet: z.enum([ - "NONE", "D_200", "PF_4_I", "PF_4_I_200", "PF_4_I_300", "PF_8_D_200", "T_200_BF", "T_300_BF", "ZPL_200", "ZPL_200_TRACKID_EAN_128", "ZPL_200_TRACKID_CODE_39", "ZPL_200_REFNO_EAN_128", "ZPL_200_REFNO_CODE_39", "ZPL_300", "ZPL_300_TRACKID_EAN_128", "ZPL_300_TRACKID_CODE_39", "ZPL_300_REFNO_EAN_128", "ZPL_300_REFNO_CODE_39" - ]), - LabelFormat: z.enum(["PDF", "ZEBRA", "INTERMEC", "DATAMAX", "TOSHIBA", "PNG"]) - }).optional(), + ReturnLabels: ReturnLabelsSchema.optional(), useDefault: z.string().max(7).optional(), DefinePrinter: z.object({ LabelPrinter: z.string().max(255).optional(), @@ -16,16 +18,37 @@ export const PrintingOptionsSchema = z.object({ }).optional(), }) export type PrintingOptions = z.infer -export type ReturnLabels = z.infer +export type ReturnLabels = z.infer export default (sdk: ActionSdk) => { return sdk.registerDataTypes( + { + identifier: "RETURN_LABELS", + type: singleZodSchemaToTypescriptDef("RETURN_LABELS", + ReturnLabelsSchema + ), + name: [ + { + code: "en-US", + content: "Return Labels" + } + ], + displayMessage: [ + { + code: "en-US", + content: "Return Labels" + } + ] + }, { identifier: "GLS_PRINTING_OPTIONS", - type: singleZodSchemaToTypescriptDef( + type: zodSchemaToTypescriptDefs( "GLS_PRINTING_OPTIONS", - PrintingOptionsSchema - ), + PrintingOptionsSchema, + { + RETURN_LABELS: ReturnLabelsSchema + } + ).get("GLS_PRINTING_OPTIONS")!, name: [ { code: "en-US", diff --git a/package-lock.json b/package-lock.json index 765c3b4..273360b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1708,14 +1708,14 @@ "license": "MIT" }, "node_modules/axios": { - "version": "1.13.6", - "resolved": "https://registry.npmjs.org/axios/-/axios-1.13.6.tgz", - "integrity": "sha512-ChTCHMouEe2kn713WHbQGcuYrr6fXTBiu460OTwWrWob16g1bXn4vtz07Ope7ewMozJAnEquLk5lWQWtBig9DQ==", + "version": "1.15.0", + "resolved": "https://registry.npmjs.org/axios/-/axios-1.15.0.tgz", + "integrity": "sha512-wWyJDlAatxk30ZJer+GeCWS209sA42X+N5jU2jy6oHTp7ufw8uzUTVFBX9+wTfAlhiJXGS0Bq7X6efruWjuK9Q==", "license": "MIT", "dependencies": { "follow-redirects": "^1.15.11", "form-data": "^4.0.5", - "proxy-from-env": "^1.1.0" + "proxy-from-env": "^2.1.0" } }, "node_modules/balanced-match": { @@ -2833,10 +2833,13 @@ } }, "node_modules/proxy-from-env": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz", - "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==", - "license": "MIT" + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-2.1.0.tgz", + "integrity": "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA==", + "license": "MIT", + "engines": { + "node": ">=10" + } }, "node_modules/punycode": { "version": "2.3.1", @@ -3144,9 +3147,9 @@ } }, "node_modules/vite": { - "version": "7.3.1", - "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.1.tgz", - "integrity": "sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==", + "version": "7.3.2", + "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.2.tgz", + "integrity": "sha512-Bby3NOsna2jsjfLVOHKes8sGwgl4TT0E6vvpYgnAYDIF/tie7MRaFthmKuHx1NSXjiTueXH3do80FMQgvEktRg==", "license": "MIT", "dependencies": { "esbuild": "^0.27.0", From 1ed39519ca31d83df83928206405003ff9fdd391 Mon Sep 17 00:00:00 2001 From: Dario Pranjic Date: Thu, 9 Apr 2026 21:02:07 +0200 Subject: [PATCH 17/17] Compile docs --- docs/Actions/GLS/types.mdx | 41 +++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/docs/Actions/GLS/types.mdx b/docs/Actions/GLS/types.mdx index 29e7376..6d259e7 100644 --- a/docs/Actions/GLS/types.mdx +++ b/docs/Actions/GLS/types.mdx @@ -964,6 +964,25 @@ Primary2D: { }} /> +# RETURN_LABELS +No documentation provided for this type. + + + # GLS_PRINTING_OPTIONS No documentation provided for this type. @@ -972,8 +991,7 @@ ReturnLabels: { description: 'No description set', deprecated: false, required: false, -typeDescriptionLink: '#gls_printing_optionsreturnlabels', - type: 'GLS_PRINTING_OPTIONS$ReturnLabels', + type: 'RETURN_LABELS', }, useDefault: { description: 'No description set', @@ -1010,25 +1028,6 @@ LabelPrinter: { }} /> -# GLS_PRINTING_OPTIONS$ReturnLabels -No documentation provided for this type. - - - # GLS_END_OF_DAY_REQUEST_DATA No documentation provided for this type.