From 797eae1b1ced67d42d137f51b973fcd430270f5e Mon Sep 17 00:00:00 2001 From: Niklas van Schrick Date: Fri, 17 Apr 2026 23:01:54 +0200 Subject: [PATCH 1/2] Update generated docs to comply with linter --- actions/gls-action/scripts/generateDocs.ts | 5 +- .../gls-action/src/functions/reprintParcel.ts | 4 +- .../src/functions/validateShipment.ts | 4 +- docs/Actions/GLS/functions.mdx | 68 +- docs/Actions/GLS/types.mdx | 1062 +++++++++-------- src/standardActionDocs.ts | 18 +- 6 files changed, 586 insertions(+), 575 deletions(-) diff --git a/actions/gls-action/scripts/generateDocs.ts b/actions/gls-action/scripts/generateDocs.ts index 27f8ffb..d417468 100644 --- a/actions/gls-action/scripts/generateDocs.ts +++ b/actions/gls-action/scripts/generateDocs.ts @@ -15,7 +15,7 @@ export function createGlsDocsConfig(): StandardActionDocsConfig { 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.`, + intro: `The GLS Action registers the following data types with the Hercules platform.\nThese types are used as inputs and outputs of the GLS functions and can be referenced in your flows.`, }, functionsCopy: { title: "Functions", @@ -33,7 +33,8 @@ export function createGlsDocsConfig(): StandardActionDocsConfig { }, { 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\`. + 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:** diff --git a/actions/gls-action/src/functions/reprintParcel.ts b/actions/gls-action/src/functions/reprintParcel.ts index ea9fc86..ebfb56c 100644 --- a/actions/gls-action/src/functions/reprintParcel.ts +++ b/actions/gls-action/src/functions/reprintParcel.ts @@ -15,7 +15,7 @@ export default (sdk: ActionSdk) => { 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." + content: "Reprints the label for an existing parcel.\nUse this if the original label is damaged, lost, or needs to be printed in a different format." } ], displayMessage: [ @@ -33,7 +33,7 @@ export default (sdk: ActionSdk) => { description: [ { 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.", + content: "Reprints the label for an existing parcel.\nUse 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/validateShipment.ts b/actions/gls-action/src/functions/validateShipment.ts index 153d48c..a50741c 100644 --- a/actions/gls-action/src/functions/validateShipment.ts +++ b/actions/gls-action/src/functions/validateShipment.ts @@ -15,7 +15,7 @@ export default (sdk: ActionSdk) => { documentation: [ { code: "en-US", - content: "Validates a shipment against the GLS API without creating it. Use this before `createShipment` functions to catch errors early." + content: "Validates a shipment against the GLS API without creating it.\nUse this before `createShipment` functions to catch errors early." } ], displayMessage: [ @@ -33,7 +33,7 @@ export default (sdk: ActionSdk) => { description: [ { code: "en-US", - content: "Validates a shipment against the GLS API without creating it. Use this before `createShipment` functions to catch errors early.", + content: "Validates a shipment against the GLS API without creating it.\nUse 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 798ed9f..ba60266 100644 --- a/docs/Actions/GLS/functions.mdx +++ b/docs/Actions/GLS/functions.mdx @@ -13,7 +13,6 @@ The GLS Action exposes functions grouped into three categories: ## Builder functions - ### `createShipmentUnit` | Parameter | Name | Type | Required | Description | @@ -27,8 +26,6 @@ The GLS Action exposes functions grouped into three categories: Return Type: [GLS_SHIPMENT_UNIT](./types.mdx#gls_shipment_unit) -# - Creates a GLS shipment unit (an individual parcel within a shipment). - -# GLS_VALIDATE_SHIPMENT_RESPONSE_DATA + +## GLS_VALIDATE_SHIPMENT_RESPONSE_DATA + No documentation provided for this type. - -# GLS_VALIDATE_SHIPMENT_RESPONSE_DATA$validationResult + +## GLS_VALIDATE_SHIPMENT_RESPONSE_DATA$validationResult + No documentation provided for this type. - -# GLS_VALIDATE_SHIPMENT_RESPONSE_DATA$validationResult$Issues + +## GLS_VALIDATE_SHIPMENT_RESPONSE_DATA$validationResult$Issues + No documentation provided for this type. - -# GLS_UPDATE_PARCEL_WEIGHT_REQUEST_DATA + +## GLS_UPDATE_PARCEL_WEIGHT_REQUEST_DATA + No documentation provided for this type. - -# GLS_UPDATE_PARCEL_WEIGHT_RESPONSE_DATA + +## GLS_UPDATE_PARCEL_WEIGHT_RESPONSE_DATA + No documentation provided for this type. - -# GLS_UNIT_SERVICE + +## GLS_UNIT_SERVICE + No documentation provided for this type. - -# GLS_UNIT_SERVICE$LimitedQuantities + +## GLS_UNIT_SERVICE$LimitedQuantities + No documentation provided for this type. - -# GLS_UNIT_SERVICE$ExWorks + +## GLS_UNIT_SERVICE$ExWorks + No documentation provided for this type. - -# GLS_UNIT_SERVICE$HazardousGoods + +## GLS_UNIT_SERVICE$HazardousGoods + No documentation provided for this type. - -# GLS_UNIT_SERVICE$HazardousGoods$HarzardousGood + +## GLS_UNIT_SERVICE$HazardousGoods$HarzardousGood + No documentation provided for this type. - -# GLS_UNIT_SERVICE$AddonLiability + +## GLS_UNIT_SERVICE$AddonLiability + No documentation provided for this type. - -# GLS_UNIT_SERVICE$Cash + +## GLS_UNIT_SERVICE$Cash + No documentation provided for this type. - -# GLS_SHIPPER + +## GLS_SHIPPER + No documentation provided for this type. - -# GLS_SHIPMENT_UNIT + +## GLS_SHIPMENT_UNIT + No documentation provided for this type. - -# GLS_SHIPMENT_UNIT$Service + +## GLS_SHIPMENT_UNIT$Service + No documentation provided for this type. - -# GLS_SHIPMENT_UNIT$Service$LimitedQuantities + +## GLS_SHIPMENT_UNIT$Service$LimitedQuantities + No documentation provided for this type. - -# GLS_SHIPMENT_UNIT$Service$ExWorks + +## GLS_SHIPMENT_UNIT$Service$ExWorks + No documentation provided for this type. - -# GLS_SHIPMENT_UNIT$Service$HazardousGoods + +## GLS_SHIPMENT_UNIT$Service$HazardousGoods + No documentation provided for this type. - -# GLS_SHIPMENT_UNIT$Service$HazardousGoods$HarzardousGood + +## GLS_SHIPMENT_UNIT$Service$HazardousGoods$HarzardousGood + No documentation provided for this type. - -# GLS_SHIPMENT_UNIT$Service$AddonLiability + +## GLS_SHIPMENT_UNIT$Service$AddonLiability + No documentation provided for this type. - -# GLS_SHIPMENT_UNIT$Service$Cash + +## GLS_SHIPMENT_UNIT$Service$Cash + No documentation provided for this type. - -# GLS_SHIPMENT + +## GLS_SHIPMENT + No documentation provided for this type. - -# GLS_SHIPMENT$Return + +## GLS_SHIPMENT$Return + No documentation provided for this type. - -# GLS_SHIPMENT_WITHOUT_SERVICES + +## GLS_SHIPMENT_WITHOUT_SERVICES + No documentation provided for this type. - -# GLS_SHIPMENT_WITHOUT_SERVICES$Return + +## GLS_SHIPMENT_WITHOUT_SERVICES$Return + No documentation provided for this type. - -# GLS_RETURN_OPTIONS + +## GLS_RETURN_OPTIONS + No documentation provided for this type. - -# GLS_REPRINT_PARCEL_REQUEST_DATA + +## GLS_REPRINT_PARCEL_REQUEST_DATA + No documentation provided for this type. - -# GLS_REPRINT_PARCEL_REQUEST_DATA$PrintingOptions + +## GLS_REPRINT_PARCEL_REQUEST_DATA$PrintingOptions + No documentation provided for this type. - -# GLS_REPRINT_PARCEL_REQUEST_DATA$PrintingOptions$ReturnLabels + +## GLS_REPRINT_PARCEL_REQUEST_DATA$PrintingOptions$ReturnLabels + No documentation provided for this type. - -# GLS_REPRINT_PARCEL_RESPONSE_DATA + +## GLS_REPRINT_PARCEL_RESPONSE_DATA + No documentation provided for this type. - -# GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment + +## GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment + No documentation provided for this type. - -# GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$PrintData + +## GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$PrintData + No documentation provided for this type. - -# GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData + +## GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData + No documentation provided for this type. - -# GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData$RoutingInfo + +## GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData$RoutingInfo + No documentation provided for this type. - -# GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData$Barcodes + +## GLS_REPRINT_PARCEL_RESPONSE_DATA$CreatedShipment$ParcelData$Barcodes + No documentation provided for this type. - -# RETURN_LABELS + +## RETURN_LABELS + No documentation provided for this type. - -# GLS_PRINTING_OPTIONS + +## GLS_PRINTING_OPTIONS + No documentation provided for this type. - -# GLS_PRINTING_OPTIONS$DefinePrinter + +## GLS_PRINTING_OPTIONS$DefinePrinter + No documentation provided for this type. - -# GLS_END_OF_DAY_REQUEST_DATA + +## GLS_END_OF_DAY_REQUEST_DATA + No documentation provided for this type. - -# GLS_END_OF_DAY_RESPONSE_DATA + +## GLS_END_OF_DAY_RESPONSE_DATA + No documentation provided for this type. - -# GLS_END_OF_DAY_RESPONSE_DATA$Shipments + +## GLS_END_OF_DAY_RESPONSE_DATA$Shipments + No documentation provided for this type. - -# GLS_END_OF_DAY_RESPONSE_DATA$Shipments$ShipmentUnit + +## GLS_END_OF_DAY_RESPONSE_DATA$Shipments$ShipmentUnit + No documentation provided for this type. - -# GLS_END_OF_DAY_RESPONSE_DATA$Shipments$Shipper + +## GLS_END_OF_DAY_RESPONSE_DATA$Shipments$Shipper + No documentation provided for this type. - -# GLS_END_OF_DAY_RESPONSE_DATA$Shipments$Consignee + +## GLS_END_OF_DAY_RESPONSE_DATA$Shipments$Consignee + No documentation provided for this type. - -# GLS_CUSTOM_CONTENT + +## GLS_CUSTOM_CONTENT + No documentation provided for this type. - -# GLS_CREATE_PARCELS_RESPONSE + +## GLS_CREATE_PARCELS_RESPONSE + No documentation provided for this type. - -# GLS_CREATE_PARCELS_RESPONSE$CreatedShipment + +## GLS_CREATE_PARCELS_RESPONSE$CreatedShipment + No documentation provided for this type. - -# GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$PrintData + +## GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$PrintData + No documentation provided for this type. - -# GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData + +## GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData + No documentation provided for this type. - -# GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData$RoutingInfo + +## GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData$RoutingInfo + No documentation provided for this type. - -# GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData$Barcodes + +## GLS_CREATE_PARCELS_RESPONSE$CreatedShipment$ParcelData$Barcodes + No documentation provided for this type. - -# GLS_CONSIGNEE + +## GLS_CONSIGNEE + No documentation provided for this type. - -# GLS_CANCEL_SHIPMENT_REQUEST_DATA + +## GLS_CANCEL_SHIPMENT_REQUEST_DATA + No documentation provided for this type. - -# GLS_CANCEL_SHIPMENT_RESPONSE_DATA + +## GLS_CANCEL_SHIPMENT_RESPONSE_DATA + No documentation provided for this type. - -# GLS_ALLOWED_SERVICES_REQUEST_DATA + +## GLS_ALLOWED_SERVICES_REQUEST_DATA + No documentation provided for this type. - -# GLS_ALLOWED_SERVICES_REQUEST_DATA$Destination + +## GLS_ALLOWED_SERVICES_REQUEST_DATA$Destination + No documentation provided for this type. - -# GLS_ALLOWED_SERVICES_REQUEST_DATA$Source + +## GLS_ALLOWED_SERVICES_REQUEST_DATA$Source + No documentation provided for this type. - -# GLS_ALLOWED_SERVICES_RESPONSE_DATA + +## GLS_ALLOWED_SERVICES_RESPONSE_DATA + No documentation provided for this type. - -# GLS_ALLOWED_SERVICES_RESPONSE_DATA$AllowedServices + +## GLS_ALLOWED_SERVICES_RESPONSE_DATA$AllowedServices + No documentation provided for this type. - -# GLS_ADDRESS + +## GLS_ADDRESS + No documentation provided for this type. - \ No newline at end of file diff --git a/src/standardActionDocs.ts b/src/standardActionDocs.ts index 5d3b9ab..a32c42c 100644 --- a/src/standardActionDocs.ts +++ b/src/standardActionDocs.ts @@ -187,9 +187,10 @@ function generateDatatypes(config: StandardActionDocsConfig, registry: RegistryS title: ${config.typesCopy.title} description: ${config.typesCopy.description} --- + import {TypeTable} from "fumadocs-ui/components/type-table"; -# ${config.typesCopy.heading} +## ${config.typesCopy.heading} ${config.typesCopy.intro} @@ -243,18 +244,20 @@ ${config.typesCopy.intro} typeString += `${property.getName()}: { description: '${docs.description}', deprecated: ${docs.deprecated}, - required: ${!property.isOptional()}, ${docs.link ? `\ntypeDescriptionLink: '#${docs.link}',` : ""} - type: '${propertyTypeText}', ${docs.default ? `\ndefault: ${docs.default}` : ""} + required: ${!property.isOptional()},${docs.link ? `\ntypeDescriptionLink: '#${docs.link}',` : ""} + type: '${propertyTypeText}',${docs.default ? `\ndefault: ${docs.default}` : ""} }, ` }) generatedDoc += ` -# ${key}${globalDocumentation || "\nNo documentation provided for this type."} +## ${key} + +${globalDocumentation || "No documentation provided for this type."} - ` +` }) }) @@ -327,8 +330,7 @@ ${config.functionsCopy.intro} generatedDoc += ` ## ${group.heading} -${group.intro ? `\n${group.intro}\n` : ""} -` +${group.intro ? `\n${group.intro}\n` : ""}` registry.runtimeFunctions.forEach(value => { const definition = value.definition @@ -368,8 +370,6 @@ ${generateMarkdownTable(headers, rows)} Return Type: ${getTypeLink(returnType || null, config) || "Unknown"} -# - ${definition.documentation?.at(0)?.content || ""} Date: Fri, 17 Apr 2026 23:02:13 +0200 Subject: [PATCH 2/2] Update docs to comply with the linter --- docs/Actions/GLS/configs.md | 25 +++++--- docs/Actions/GLS/events.md | 11 ++-- docs/Actions/GLS/overview.md | 26 ++++---- docs/Actions/GLS/quick-start.md | 12 ++-- docs/Actions/GLS/troubleshooting.md | 98 ++++++++++++----------------- docs/Actions/GLS/use-cases.md | 80 +++++++++++++---------- docs/index.mdx | 9 ++- docs/installation.md | 14 ++--- 8 files changed, 141 insertions(+), 134 deletions(-) diff --git a/docs/Actions/GLS/configs.md b/docs/Actions/GLS/configs.md index fa374e1..7572144 100644 --- a/docs/Actions/GLS/configs.md +++ b/docs/Actions/GLS/configs.md @@ -3,9 +3,8 @@ title: Configuration description: All configuration options for the GLS Action, including how to obtain credentials from the GLS Developer Portal. --- -# GLS Action Configuration - -The GLS action requires a few credentials to authenticate with the GLS ShipIT API. These are set as **configuration values** in the Hercules admin panel (not as environment variables). +The GLS action requires a few credentials to authenticate with the GLS ShipIT API. +These are set as **configuration values** in the Hercules admin panel (not as environment variables). --- @@ -20,7 +19,8 @@ The GLS action requires a few credentials to authenticate with the GLS ShipIT AP | `auth_url` | string | No | `https://api.gls-group.net/oauth2/v2/token` | GLS OAuth2 token endpoint — must end in `/token` | | `shipper` | GLS_SHIPPER | No | — | Default shipper address used when no shipper is provided in the shipment data | -> **`contact_id`:** This identifier is required for certain shipment operations (e.g. end-of-day reports and some services). It is issued by GLS support — contact them directly to request it. +> **`contact_id`:** This identifier is required for certain shipment operations (e.g. end-of-day reports and some services). +> It is issued by GLS support — contact them directly to request it. --- @@ -28,7 +28,7 @@ The GLS action requires a few credentials to authenticate with the GLS ShipIT AP ### Step 1 — Create a GLS Developer account -1. Go to [https://dev-portal.gls-group.net/get-started](https://dev-portal.gls-group.net/get-started) +1. Go to 2. Click **Sign In** and register a new account, or log in with an existing GLS account 3. Complete the registration and verify your email address @@ -50,13 +50,15 @@ The GLS action requires a few credentials to authenticate with the GLS ShipIT AP ### Step 4 — Get your Contact ID (optional) -The `contact_id` is not available in the developer portal. You must contact **GLS support** directly and ask them to provide you with a Contact ID linked to your GLS contract. +The `contact_id` is not available in the developer portal. +You must contact **GLS support** directly and ask them to provide you with a Contact ID linked to your GLS contract. --- ## API endpoints -GLS provides different API endpoints depending on your region and environment. The defaults point to the global production API: +GLS provides different API endpoints depending on your region and environment. +The defaults point to the global production API: | Setting | Default URL | |---------|-------------| @@ -71,7 +73,7 @@ If you are using a regional or sandbox endpoint, update these values accordingly The GLS Action authenticates using **OAuth2 client credentials**: -``` +```text GLS Action │ ├── POST {auth_url} @@ -85,13 +87,16 @@ GLS Action Authorization: Bearer ``` -Tokens are **cached** and automatically refreshed 60 seconds before they expire. You do not need to manage token lifecycle manually. +Tokens are **cached** and automatically refreshed 60 seconds before they expire. +You do not need to manage token lifecycle manually. --- ## Default shipper -The optional `shipper` config allows you to set a **default sender address** that is applied to all shipments when no shipper is explicitly provided in the shipment data. This is useful when all your shipments originate from the same address. +The optional `shipper` config allows you to set a **default sender address** that is applied to all shipments when +no shipper is explicitly provided in the shipment data. +This is useful when all your shipments originate from the same address. The value must be a valid `GLS_SHIPPER` object: diff --git a/docs/Actions/GLS/events.md b/docs/Actions/GLS/events.md index a9e6e9c..da51c64 100644 --- a/docs/Actions/GLS/events.md +++ b/docs/Actions/GLS/events.md @@ -3,9 +3,11 @@ title: Trigger description: Events emitted by the GLS Action — what they are, how they trigger flows in Aquila, and what future events are planned. --- -# GLS Action Events +## GLS Action Events -In the Hercules platform, **events** are notifications emitted **by an action** that trigger flows in Aquila. They are the opposite of functions: instead of a flow calling the action, the action pushes data to Aquila, which starts any flows that are listening for that event type. +In the Hercules platform, **events** are notifications emitted **by an action** that trigger flows in Aquila. +They are the opposite of functions: instead of a flow calling the action, the action pushes data to Aquila, which starts +any flows that are listening for that event type. --- @@ -13,6 +15,7 @@ In the Hercules platform, **events** are notifications emitted **by an action** > **The GLS Action does not currently emit any events.** > -> The GLS action presently only exposes **functions** (called by flows) and registers **data types** and **configuration**. Event support — where the action proactively notifies Aquila of changes — is **planned for a future release**. +> The GLS action presently only exposes **functions** (called by flows) and registers **data types** and **configuration**. +> Event support — where the action proactively notifies Aquila of changes — is **planned for a future release**. ---- \ No newline at end of file +--- diff --git a/docs/Actions/GLS/overview.md b/docs/Actions/GLS/overview.md index 6b05243..896b3d0 100644 --- a/docs/Actions/GLS/overview.md +++ b/docs/Actions/GLS/overview.md @@ -4,9 +4,9 @@ description: Overview of the GLS ShipIT action — what it does, what you need t icon: IconHome --- -# GLS Action - -The **GLS Action** integrates the [GLS ShipIT API](https://dev-portal.gls-group.net/docs/shipit-farm/1/overview) as an action. It lets you create, validate, cancel, and manage GLS parcel shipments directly from your flows — no manual API calls required. +The **GLS Action** integrates the [GLS ShipIT API](https://dev-portal.gls-group.net/docs/shipit-farm/1/overview) as an action. +It lets you create, validate, cancel, and manage GLS parcel shipments directly from your +flows — no manual API calls required. --- @@ -37,19 +37,20 @@ Before using the GLS Action you will need: ### GLS Developer Portal -| Requirement | How to obtain | -|---------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| `client_id` | Create an application at [https://dev-portal.gls-group.net](https://dev-portal.gls-group.net) and find it under **My Apps** | -| `client_secret` | Found alongside the `client_id` in **My Apps** on the GLS developer portal | -| `contact_id` *(optional)* | Issued by GLS support — contact them directly to request it | +| Requirement | How to obtain | +|---------------------------|-------------------------------------------------------------------------------------------| +| `client_id` | Create an application at and find it under **My Apps** | +| `client_secret` | Found alongside the `client_id` in **My Apps** on the GLS developer portal | +| `contact_id` *(optional)* | Issued by GLS support — contact them directly to request it | -> **Note:** The `contact_id` is required for some shipment operations. If you are unsure whether you need it, contact GLS support. +> **Note:** The `contact_id` is required for some shipment operations. +> If you are unsure whether you need it, contact GLS support. --- ## Architecture overview -``` +```text Your Flow │ ▼ @@ -62,13 +63,14 @@ Your Flow └── GLS ShipIT API (/shipit-farm/v1/backend/rs/...) ``` -The action handles OAuth2 token management automatically, including caching and refresh before expiry. You only need to provide the `client_id` and `client_secret` in the action configuration. +The action handles OAuth2 token management automatically, including caching and refresh before expiry. +You only need to provide the `client_id` and `client_secret` in the action configuration. --- ## Data flow -``` +```text Flow Input │ ▼ diff --git a/docs/Actions/GLS/quick-start.md b/docs/Actions/GLS/quick-start.md index 80fab6f..63bd534 100644 --- a/docs/Actions/GLS/quick-start.md +++ b/docs/Actions/GLS/quick-start.md @@ -3,15 +3,15 @@ title: Quick Start description: Create your first GLS shipment in a few steps. --- -# Quick Start - -This guide walks you through creating your first GLS shipment using the GLS Action. By the end, you will have a working flow that creates a parcel and retrieves a shipping label. +This guide walks you through creating your first GLS shipment using the GLS Action. +By the end, you will have a working flow that creates a parcel and retrieves a shipping label. --- ## Step 1: Install and configure the action -Follow the [Installation Guide](../../installation.md) to deploy the GLS Action, then set the following configuration values in your Hercules admin panel (or `.env` file): +Follow the [Installation Guide](../../installation.md) to deploy the GLS Action, then set the following configuration values in +your Hercules admin panel (or `.env` file): | Config | Value | |-------------------|--------------------------------------------------------------------------------------| @@ -28,7 +28,7 @@ See [Configuration](configs.md) for the full list of options and how to obtain c A basic "create a GLS parcel" flow looks like this: -``` +```text [createAddress] → GLS_ADDRESS (recipient) [createAddress] → GLS_ADDRESS (shipper) [createShipmentUnit] → GLS_SHIPMENT_UNIT @@ -38,7 +38,7 @@ A basic "create a GLS parcel" flow looks like this: ### Flow diagram -``` +```text START │ ├─ createAddress (recipient) diff --git a/docs/Actions/GLS/troubleshooting.md b/docs/Actions/GLS/troubleshooting.md index ec8d12c..0aa13b1 100644 --- a/docs/Actions/GLS/troubleshooting.md +++ b/docs/Actions/GLS/troubleshooting.md @@ -3,23 +3,19 @@ title: Troubleshooting description: Frequently asked questions, troubleshooting tips, and community resources for the GLS Action. --- -# Troubleshooting & Community Support - ---- - ## FAQ ### General -**Q: What is the GLS Action?** +#### What is the GLS Action? -A: The GLS Action is an integration for the Hercules automation platform that connects to the [GLS ShipIT API](https://api.gls-group.net). It lets you create and manage GLS shipments from within your flows without writing any API code. +The GLS Action is an integration for the Hercules automation platform that connects to the [GLS ShipIT API](https://api.gls-group.net). +It lets you create and manage GLS shipments from within your flows without writing any API code. ---- +#### What GLS services does this action support? -**Q: What GLS services does this action support?** +The action supports all major GLS shipment types and services, including: -A: The action supports all major GLS shipment types and services, including: - Standard parcel delivery - Shop delivery and shop returns - Exchange shipments @@ -32,82 +28,71 @@ A: The action supports all major GLS shipment types and services, including: See [Functions](functions.mdx) for the complete list. ---- - -**Q: Do I need a paid GLS account?** - -A: Yes. You need a GLS business account and API access. Register on the [GLS Developer Portal](https://dev-portal.gls-group.net) and create an application to obtain `client_id` and `client_secret`. - ---- - -**Q: What is the `contact_id` and do I need it?** +#### Do I need a paid GLS account? -A: The `contact_id` is a GLS-assigned identifier linked to your contract. It is required for some advanced operations (e.g. retrieving end-of-day reports with your account data). Contact GLS support to request it. It is **optional** for basic shipment creation. +Yes. You need a GLS business account and API access. +Register on the [GLS Developer Portal](https://dev-portal.gls-group.net) and create an application to obtain `client_id` and `client_secret`. ---- +#### What is the `contact_id` and do I need it? -**Q: Can I test the action without a real GLS account?** +The `contact_id` is a GLS-assigned identifier linked to your contract. +It is required for some advanced operations (e.g. retrieving end-of-day reports with your account data). +Contact GLS support to request it. It is **optional** for basic shipment creation. -A: GLS provides sandbox/test environments for some regions. Check the [GLS Developer Portal](https://dev-portal.gls-group.net) for sandbox API endpoint URLs and test credentials. Update `ship_it_api_url` and `auth_url` in your configuration to point to the sandbox endpoints. +#### Can I test the action without a real GLS account? ---- +GLS provides sandbox/test environments for some regions. +Check the [GLS Developer Portal](https://dev-portal.gls-group.net) for sandbox API endpoint URLs and test credentials. +Update `ship_it_api_url` and `auth_url` in your configuration to point to the sandbox endpoints. ### Installation & configuration -**Q: The action starts but immediately disconnects. What's wrong?** +#### The action starts but immediately disconnects. What's wrong? + +Check the following: -A: Check the following: 1. `HERCULES_AUTH_TOKEN` — is it valid and not expired? 2. `HERCULES_AQUILA_URL` — is the Aquila server reachable from the Docker container? 3. Docker logs: `docker compose logs -f` — look for specific error messages ---- - ### Authentication & API errors -**Q: I get an `INVALID_PRODUCT` error when creating a Saturday delivery shipment.** - -A: Saturday delivery (and next-working-day delivery) requires the shipment's `Product` to be set to `"EXPRESS"`. Change `Product: "PARCEL"` to `Product: "EXPRESS"` in your shipment data. - ---- - -**Q: I get `ERROR_CREATING_GLS_SHIPMENT` — how do I find out what went wrong?** +#### I get an `INVALID_PRODUCT` error when creating a Saturday delivery shipment -A: Use `validateShipment` first to check your shipment data before creating it. The validation response includes specific `Issues` with `Rule` and `Location` fields pointing to the problematic field. See [Use Cases — Validate before creating](../GLS/use-cases.md#use-case-2-validate-before-creating). +Saturday delivery (and next-working-day delivery) requires the shipment's `Product` to be set to `"EXPRESS"`. +Change `Product: "PARCEL"` to `Product: "EXPRESS"` in your shipment data. ---- +#### I get `ERROR_CREATING_GLS_SHIPMENT` — how do I find out what went wrong? -**Q: Can I cancel a shipment after it has been picked up by GLS?** +Use `validateShipment` first to check your shipment data before creating it. +The validation response includes specific `Issues` with `Rule` and `Location` fields pointing to the problematic field. +See [Use Cases — Validate before creating](../GLS/use-cases.md#use-case-2-validate-before-creating). -A: No. Once GLS has scanned the parcel at a depot or delivery vehicle, cancellation is no longer possible. The `cancelShipment` function will return `result: "SCANNED"` in that case. - ---- +#### Can I cancel a shipment after it has been picked up by GLS? +No. Once GLS has scanned the parcel at a depot or delivery vehicle, cancellation is no longer possible. +The `cancelShipment` function will return `result: "SCANNED"` in that case. ### Labels & printing -**Q: What label formats are supported?** +#### What label formats are supported? -A: The action supports: `PDF`, `ZEBRA`, `INTERMEC`, `DATAMAX`, `TOSHIBA`, `PNG`. For reprint, additionally `PNG_200`. +The action supports: `PDF`, `ZEBRA`, `INTERMEC`, `DATAMAX`, `TOSHIBA`, `PNG`. For reprint, additionally `PNG_200`. Choose the format that matches your label printer. ---- +#### The label data returned is base64-encoded. How do I print it? -**Q: The label data returned is base64-encoded. How do I print it?** +Decode `CreatedShipment.PrintData[0].Data` from base64, then: -A: Decode `CreatedShipment.PrintData[0].Data` from base64, then: - **PDF:** Save as a `.pdf` file and send to a PDF-capable printer - **ZPL (ZEBRA):** Send the raw ZPL string directly to a Zebra label printer - **PNG:** Save as a `.png` file and print as an image ---- - -**Q: Can I reprint a label after the parcel has been dispatched?** +#### Can I reprint a label after the parcel has been dispatched? -A: Yes, use the `reprintParcel` function with the `TrackID` and the original `CreationDate`. Note that available template sets for reprinting are limited to `NONE`, `ZPL_200`, and `ZPL_300`. - ---- +Yes, use the `reprintParcel` function with the `TrackID` and the original `CreationDate`. +Note that available template sets for reprinting are limited to `NONE`, `ZPL_200`, and `ZPL_300`. ## Common error codes @@ -116,8 +101,6 @@ A: Yes, use the `reprintParcel` function with the `TrackID` and the original `Cr | `ERROR_CREATING_GLS_SHIPMENT` | API returned an error during shipment creation or management | Check `validateShipment` output for details | | `INVALID_PRODUCT` | Used `"PARCEL"` product with a service that requires `"EXPRESS"` | Set `Product: "EXPRESS"` in the shipment | ---- - ## Still stuck? If you cannot resolve your issue with the FAQ above: @@ -126,21 +109,18 @@ If you cannot resolve your issue with the FAQ above: 2. **Check the GLS API status:** Visit the [GLS Developer Portal](https://dev-portal.gls-group.net) for service announcements 3. **Open an issue** on GitHub (see below) ---- - ## GitHub The source code for the GLS Action and all other Centaurus actions is available on GitHub: -🔗 **[https://github.com/code0-tech/centaurus](https://github.com/code0-tech/centaurus)** +🔗 **** Use the GitHub repository to: + - **Report bugs:** Open an [issue](https://github.com/code0-tech/centaurus/issues) - **Request features:** Open a [discussion](https://github.com/code0-tech/centaurus/discussions) or issue with the `enhancement` label - **Ask questions:** Use [GitHub Discussions](https://github.com/code0-tech/centaurus/discussions) ---- - ## Contributing Contributions to Centaurus are welcome! Here is how to get started: @@ -173,6 +153,7 @@ This creates a new directory at `actions/my-new-action/` with the standard struc ### 4. Submit a pull request Open a pull request against the `main` branch of [code0-tech/centaurus](https://github.com/code0-tech/centaurus). Include: + - A clear description of what you changed and why - Test results showing your changes pass @@ -185,4 +166,3 @@ Open a pull request against the `main` branch of [code0-tech/centaurus](https:// | `npm run test:watch` | Run tests in watch mode | | `npm run lint` | Run ESLint | | `npm run create-action -- ` | Scaffold a new action | - diff --git a/docs/Actions/GLS/use-cases.md b/docs/Actions/GLS/use-cases.md index 1a36bfb..50a4b37 100644 --- a/docs/Actions/GLS/use-cases.md +++ b/docs/Actions/GLS/use-cases.md @@ -3,9 +3,8 @@ title: Common Use Cases description: End-to-end example flows using the GLS Action for real-world shipping scenarios. --- -# Common Use Cases - -This page shows complete, real-world examples of flows built with the GLS Action. Each example includes a step-by-step breakdown and the data passed between functions. +This page shows complete, real-world examples of flows built with the GLS Action. +Each example includes a step-by-step breakdown and the data passed between functions. --- @@ -15,7 +14,7 @@ This page shows complete, real-world examples of flows built with the GLS Action ### Flow -``` +```text [createAddress] (recipient) │ GLS_ADDRESS [createAddress] (shipper) @@ -31,8 +30,9 @@ This page shows complete, real-world examples of flows built with the GLS Action ### Step-by-step -**1. Create recipient address** -``` +#### 1. Create recipient address + +```text createAddress( Name1: "Jane Smith", CountryCode: "DE", @@ -45,8 +45,9 @@ createAddress( → GLS_ADDRESS (recipient) ``` -**2. Create parcel unit** -``` +#### 2. Create parcel unit + +```text createShipmentUnit( weight: 1.2, shipmentUnitReference: "ORDER-12345", @@ -55,8 +56,9 @@ createShipmentUnit( → GLS_SHIPMENT_UNIT ``` -**3. Set printing options** -``` +#### 3. Set printing options + +```text createPrintingOptions( returnLabels: { TemplateSet: "NONE", @@ -66,8 +68,9 @@ createPrintingOptions( → GLS_PRINTING_OPTIONS ``` -**4. Create the shipment** (using default shipper from config) -``` +#### 4. Create the shipment (using default shipper from config) + +```text createShopDeliveryShipment( parcelShopId: "PSH-HH-001", shipment: { @@ -85,7 +88,8 @@ createShopDeliveryShipment( → GLS_CREATE_PARCELS_RESPONSE ``` -**5. Use the response** +#### 5. Use the response + - Store `CreatedShipment.ParcelData[0].TrackID` in your order database - Decode `CreatedShipment.PrintData[0].Data` (base64 PDF) and send to printer @@ -97,7 +101,7 @@ createShopDeliveryShipment( ### Flow -``` +```text [Build shipment data] → GLS_SHIPMENT │ [validateShipment] @@ -112,8 +116,9 @@ createShopDeliveryShipment( ### Example -**1. Validate the shipment** -``` +#### 1. Validate the shipment + +```text validateShipment({ Shipment: { Product: "PARCEL", @@ -133,7 +138,8 @@ validateShipment({ → GLS_VALIDATE_SHIPMENT_RESPONSE_DATA ``` -**2. Check the result** +#### 2. Check the result + ```json { "success": true, @@ -142,6 +148,7 @@ validateShipment({ ``` If `success` is `false`, inspect `validationResult.Issues` for details: + ```json { "success": false, @@ -165,7 +172,7 @@ If `success` is `false`, inspect `validationResult.Issues` for details: ### Flow -``` +```text [createAddress] (your warehouse as consignee for return) │ [createShipmentUnit] @@ -180,7 +187,7 @@ If `success` is `false`, inspect `validationResult.Issues` for details: ### Example -``` +```text createShopReturnShipment( numberOfLabels: 1, shipment: { @@ -209,6 +216,7 @@ createShopReturnShipment( ``` **Customer flow:** + 1. Receive the PDF label by email 2. Print it (or show QR code on phone) 3. Drop off at any GLS Parcel Shop @@ -217,11 +225,12 @@ createShopReturnShipment( ## Use Case 4: Identity-verified delivery (age-restricted goods) -**Scenario:** You are shipping age-restricted goods (e.g. alcohol, medication) and need to verify the recipient's identity on delivery. +**Scenario:** You are shipping age-restricted goods (e.g. alcohol, medication) and need +to verify the recipient's identity on delivery. ### Flow -``` +```text [createShipmentUnit] │ [createPrintingOptions] @@ -232,7 +241,7 @@ createShopReturnShipment( ### Example -``` +```text createIdentShipment( birthDate: "1990-05-15", firstName: "Hans", @@ -261,17 +270,19 @@ createIdentShipment( ) ``` -The GLS driver will verify the recipient's ID against the provided name, birthdate, and nationality before handing over the parcel. +The GLS driver will verify the recipient's ID against the provided name, birthdate, +and nationality before handing over the parcel. --- ## Use Case 5: End-of-day reconciliation -**Scenario:** At the end of each business day, you want to fetch all shipments dispatched that day and reconcile them with your order management system. +**Scenario:** At the end of each business day, you want to fetch all shipments dispatched that day and +reconcile them with your order management system. ### Flow -``` +```text [getEndOfDayReport({ date: "2025-01-15" })] │ GLS_END_OF_DAY_RESPONSE_DATA │ @@ -282,7 +293,7 @@ The GLS driver will verify the recipient's ID against the provided name, birthda ### Example -``` +```text getEndOfDayReport({ date: "2025-01-15" }) @@ -290,6 +301,7 @@ getEndOfDayReport({ ``` Response: + ```json { "Shipments": [ @@ -315,7 +327,7 @@ Response: ### Flow -``` +```text [reprintParcel({ TrackID, CreationDate, PrintingOptions })] │ GLS_REPRINT_PARCEL_RESPONSE_DATA │ @@ -324,7 +336,7 @@ Response: ### Example -``` +```text reprintParcel({ TrackID: "12345678", CreationDate: "2025-01-15", @@ -342,11 +354,12 @@ reprintParcel({ ## Use Case 7: Check available services for a route -**Scenario:** Before creating a shipment, you want to check which GLS services are available between your depot (Berlin, DE) and a customer in France (Paris, 75001). +**Scenario:** Before creating a shipment, you want to check which GLS services are available between your depot +(Berlin, DE) and a customer in France (Paris, 75001). ### Flow -``` +```text [getAllowedServices({ Source, Destination })] │ GLS_ALLOWED_SERVICES_RESPONSE_DATA │ @@ -355,7 +368,7 @@ reprintParcel({ ### Example -``` +```text getAllowedServices({ Source: { CountryCode: "DE", @@ -370,6 +383,7 @@ getAllowedServices({ ``` Response: + ```json { "AllowedServices": [ @@ -392,7 +406,7 @@ Use this to dynamically enable/disable delivery options in your checkout flow. ### Flow -``` +```text [createShipmentUnit] │ [createPrintingOptions] @@ -403,7 +417,7 @@ Use this to dynamically enable/disable delivery options in your checkout flow. ### Example -``` +```text createDeliverySaturdayShipment( shipment: { Product: "EXPRESS", ← required! diff --git a/docs/index.mdx b/docs/index.mdx index 6ddc0a0..f961b23 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -6,9 +6,12 @@ template: splash ## What is Centaurus? -Centaurus is a monorepo containing a collection of **actions** provided by [code0](https://github.com/code0-tech). Actions are integrations that connect external services to the **Hercules** automation platform, allowing you to build powerful workflows without writing boilerplate code. +Centaurus is a monorepo containing a collection of **actions** provided by [code0](https://github.com/code0-tech). +Actions are integrations that connect external services to the **Hercules** automation platform, allowing you to build +powerful workflows without writing boilerplate code. -Each action exposes **functions**, **data types**, and **configuration** that can be composed inside flows to automate real-world tasks such as shipping logistics, notifications, payments, and more. +Each action exposes **functions**, **data types**, and **configuration** that can be composed inside flows to automate +real-world tasks such as shipping logistics, notifications, payments, and more. --- @@ -40,4 +43,4 @@ Before using any action from Centaurus, make sure you have: - [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 +- [Troubleshooting](Actions/GLS/troubleshooting.md) — FAQ and community support diff --git a/docs/installation.md b/docs/installation.md index 4e51e81..cb97105 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,17 +2,17 @@ title: Installation guide for actions --- -# Cloud edition +## Cloud edition The cloud edition is managed by code0 and requires no installation. Contact the code0 team for access. --- -# Self-hosted +## Self-hosted To install an action on your self-hosted instance, follow these steps: -## Prerequisites +### Prerequisites Before you begin, make sure you have the following: @@ -64,7 +64,7 @@ Then open `.env` in your editor and set the required variables: Example `.env` for the GLS action: -``` +```text HERCULES_AUTH_TOKEN=your_hercules_auth_token HERCULES_AQUILA_URL=your-aquila-host:50051 HERCULES_ACTION_ID=gls-action @@ -89,7 +89,7 @@ docker compose logs -f A successful startup will show: -``` +```text SDK connected successfully ``` @@ -97,7 +97,8 @@ SDK connected successfully ## 5. Verify the action is registered -Open your Hercules/Aquila admin panel and navigate to the **Actions** section. The action should appear in the list with its registered functions and types. +Open your Hercules/Aquila admin panel and navigate to the **Actions** section. +The action should appear in the list with its registered functions and types. --- @@ -120,4 +121,3 @@ If the action fails to start or connect, check: - That `HERCULES_AQUILA_URL` points to the correct host and port - That Docker has access to the internet (for pulling the base image) - The service-specific credentials are correct (see [Troubleshooting](Actions/GLS/troubleshooting.md)) -