Refine docs

Knerio · Knerio · commit fd0ea43e8877 · 2026-03-19T13:51:23.000+01:00
diff --git a/actions/gls-action/src/helpers.ts b/actions/gls-action/src/helpers.ts
@@ -245,7 +245,7 @@ export function transformValidateShipmentRequestDataToInternalFormat(data: Valid
         Shipment: {
             ...data.Shipment,
             Middleware: "CodeZeroviaGLS",
-            Shipper: getShipper(data.Shipment.Shipper, context, contactID),
+            Shipper: getShipper(context, contactID, data.Shipment.Shipper),
             Service: InternalShipmentServiceSchema.parse(data.Shipment.Service),
             ShipmentUnit: InternalShipmentUnitSchema.parse(data.Shipment.ShipmentUnit)
         }
@@ -258,27 +258,31 @@ function transformShipmentRequestDataToInternalFormat(data: ShipmentRequestData,
         Shipment: {
             ...data.Shipment,
             Middleware: "CodeZeroviaGLS",
-            Shipper: getShipper(data.Shipment.Shipper, context, contactID),
+            Shipper: getShipper(context, contactID, data.Shipment.Shipper),
             Service: InternalShipmentServiceSchema.parse(data.Shipment.Service),
             ShipmentUnit: InternalShipmentUnitSchema.parse(data.Shipment.ShipmentUnit)
         }
     }
 }
 
-function getShipper(shipper: Shipper, context: HerculesFunctionContext | undefined, contactID: string | undefined): InternalShipper {
+function getShipper(context: HerculesFunctionContext | undefined, contactID: string | undefined, shipper?: Shipper): InternalShipper {
     const configShipper = context?.matchedConfig.findConfig("shipper") as Shipper || undefined
 
-    if (configShipper) {
-        return {
-            ...configShipper,
-            ContactID: contactID
-        }
-    } else {
+    if (!shipper && !configShipper) {
+        throw new RuntimeErrorException("MISSING_SHIPPER_INFORMATION", "No shipper information provided in shipment data or configuration.")
+    }
+
+    if (shipper) {
         return {
             ...shipper,
             ContactID: contactID
         }
     }
+
+    return {
+        ...configShipper,
+        ContactID: contactID
+    }
 }
 
 export async function postShipmentHelper(context: HerculesFunctionContext, services: ShipmentService, shipment: ShipmentWithoutServices, printingOptions: PrintingOptions, customContent?: CustomContent, returnOptions?: ReturnOptions): Promise<CreateParcelsResponse> {
diff --git a/actions/gls-action/src/types.ts b/actions/gls-action/src/types.ts
@@ -309,7 +309,7 @@ export const ShipmentSchema = z.object({
     Product: z.enum(["PARCEL", "EXPRESS"]),
     ExpressAltDeliveryAllowed: z.boolean().optional(),
     Consignee: ConsigneeSchema,
-    Shipper: ShipperSchema,
+    Shipper: ShipperSchema.optional(),
     Carrier: z.enum(["ROYALMAIL"]).optional(),
     ShipmentUnit: ShipmentUnitSchema,
     Service: ShipmentServiceSchema,
diff --git 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#GLS_SHIPPER) for the full field reference.
+See [Types — GLS_SHIPPER](../types/#GLS_SHIPPER) for the full field reference.
diff --git a/docs/Actions/GLS/events.md b/docs/Actions/GLS/events.md
@@ -9,166 +9,10 @@ In the Hercules platform, **events** are notifications emitted **by an action**
 
 ---
 
-## How events work
-
-```
-External world (e.g. GLS webhook / polling)
-          │
-          │ something happens (parcel delivered, shipment arrived, ...)
-          ▼
-    GLS Action
-          │
-          │  sdk.dispatchEvent(eventType, projectId, payload)
-          ▼
-       Aquila
-          │
-          │  routes event to all flows listening for eventType
-          ▼
-     Your Flow starts
-          │
-          │  event payload available as flow input
-          ▼
-     Flow nodes execute (functions, conditions, etc.)
-```
-
-An event carries a **payload** — the data associated with what happened (e.g. shipment details, tracking ID, status). Flows that subscribe to an event type receive this payload as their starting input.
-
----
-
 ## Current status
 
 > **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**.
 
----
-
-## Planned events
-
-The following events are candidates for future implementation. Once added, each will allow you to build flows that react automatically to GLS shipment lifecycle changes.
-
-### `gls.shipment.arrived`
-
-Emitted when a parcel arrives at a GLS depot or is scanned into the GLS network.
-
-**Trigger mechanism:** The action would periodically poll the GLS tracking API (or receive a GLS webhook) and emit this event for each new scan.
-
-**Payload type (planned):** `GLS_TRACKING_EVENT`
-
-```
-GLS Action (polling / webhook listener)
-      │
-      │  detects new scan for tracked parcel
-      ▼
-sdk.dispatchEvent("gls.shipment.arrived", projectId, {
-  TrackID: "12345678",
-  Status: "IN_TRANSIT",
-  Location: "MUC-HUB",
-  Timestamp: "2025-06-01T10:30:00Z"
-})
-      │
-      ▼
-Aquila → triggers all flows subscribed to "gls.shipment.arrived"
-```
-
----
-
-### `gls.shipment.delivered`
-
-Emitted when a parcel is confirmed delivered to the recipient.
-
-**Payload type (planned):** `GLS_TRACKING_EVENT`
-
-```
-sdk.dispatchEvent("gls.shipment.delivered", projectId, {
-  TrackID: "12345678",
-  Status: "DELIVERED",
-  DeliveredAt: "2025-06-02T14:15:00Z",
-  SignedBy: "J. Doe"
-})
-```
-
----
-
-### `gls.shipment.failed`
-
-Emitted when a delivery attempt fails (e.g. recipient not home, address problem).
-
-**Payload type (planned):** `GLS_TRACKING_EVENT`
-
-```
-sdk.dispatchEvent("gls.shipment.failed", projectId, {
-  TrackID: "12345678",
-  Status: "DELIVERY_FAILED",
-  Reason: "RECIPIENT_NOT_HOME",
-  NextAttempt: "2025-06-03"
-})
-```
-
----
-
-### `gls.shipment.returned`
-
-Emitted when a parcel is returned to sender after failed delivery attempts.
-
----
-
-## How events are implemented (SDK reference)
-
-When events are added to the GLS Action, they will follow this pattern from the Hercules SDK:
-
-### 1. Register the flow type (event definition)
-
-```typescript
-sdk.registerFlowTypes({
-  identifier: "gls.shipment.arrived",
-  editable: false,
-  inputType: "GLS_TRACKING_EVENT",
-  linkedDataTypes: ["GLS_TRACKING_EVENT"],
-  name: [{ code: "en-US", content: "GLS Shipment Arrived" }],
-  description: [{
-    code: "en-US",
-    content: "Triggered when a GLS parcel arrives at a depot or is scanned."
-  }]
-})
-```
-
-### 2. Dispatch the event when it occurs
-
-```typescript
-sdk.dispatchEvent(
-  "gls.shipment.arrived",  // must match registered flow type identifier
-  projectId,               // which project to notify
-  payload                  // data payload (must match inputType)
-)
-```
-
-### 3. User builds a flow triggered by the event
-
-In the Hercules UI, users create a flow with **"GLS Shipment Arrived"** as the trigger. When the GLS action dispatches this event, Aquila starts the flow and provides the payload (e.g. `TrackID`, `Status`, `Location`) as the flow's input.
-
----
-
-## Flow type settings
-
-Flow types can expose **settings** that allow users to configure how an event filters or behaves. For example, a future `gls.shipment.arrived` event might let users specify:
-
-| Setting | Type | Description |
-|---------|------|-------------|
-| `trackId` | string | Only trigger for a specific parcel |
-| `statusFilter` | string[] | Only trigger for specific status codes |
-
-Settings are defined in the `settings` array of `HerculesFlowType` and are configurable per-flow in the Hercules UI.
-
----
-
-## Difference between events and functions
-
-| | Events | Functions |
-|-|--------|-----------|
-| **Direction** | Action → Aquila | Flow → Action |
-| **Who initiates** | The action (proactively) | The flow (on demand) |
-| **Purpose** | React to something that happened externally | Perform an operation and return a result |
-| **SDK method** | `registerFlowTypes` + `dispatchEvent` | `registerFunctionDefinitions` |
-| **Example** | Parcel delivered → trigger notification flow | Create a shipment and return the label |
-| **Current GLS status** | ❌ Not yet implemented | ✅ 26 functions available |
+---
diff --git 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#GLS_ADDRESS)
+**Returns:** [`GLS_ADDRESS`](../types#GLS_ADDRESS)
 
 ---
 
@@ -83,7 +83,7 @@ createConsignee(
 | `Address` | 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#GLS_CONSIGNEE)
+**Returns:** [`GLS_CONSIGNEE`](../types#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#GLS_SHIPMENT_UNIT)
+**Returns:** [`GLS_SHIPMENT_UNIT`](../types#GLS_SHIPMENT_UNIT)
 
 ---
 
@@ -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#GLS_PRINTING_OPTIONS)
+**Returns:** [`GLS_PRINTING_OPTIONS`](../types#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#GLS_CUSTOM_CONTENT)
+**Returns:** [`GLS_CUSTOM_CONTENT`](../types#GLS_CUSTOM_CONTENT)
 
 ---
 
@@ -536,7 +536,7 @@ validateShipment
       └── validationResult.Issues[]
 ```
 
-See [Types — GLS_VALIDATE_SHIPMENT_REQUEST_DATA](./types#GLS_VALIDATE_SHIPMENT_REQUEST_DATA) for the input format.
+See [Types — GLS_VALIDATE_SHIPMENT_REQUEST_DATA](../types#GLS_VALIDATE_SHIPMENT_REQUEST_DATA) for the input format.
 
 ---
 
diff --git a/docs/Actions/GLS/overview.md b/docs/Actions/GLS/overview.md
@@ -5,7 +5,7 @@ description: Overview of the GLS ShipIT action — what it does, what you need t
 
 # GLS Action
 
-The **GLS Action** integrates the [GLS ShipIT API](https://api.gls-group.net) into the Hercules automation platform. 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.
 
 ---
 
@@ -49,7 +49,7 @@ Before using the GLS Action you will need:
 ## Architecture overview
 
 ```
-Your Flow (Hercules)
+Your Flow
        │
        ▼
  GLS Action (this action)
@@ -87,10 +87,10 @@ GLS_CREATE_PARCELS_RESPONSE  ← tracking IDs, barcode data, print data, routing
 
 ## Next steps
 
-- [Quick Start](./quick-start) — Create your first shipment in a few steps
-- [Configuration](./configs) — Full list of configuration options and how to get credentials
-- [Functions](./functions) — All available functions with parameter details
-- [Types](./types) — All data types used in the GLS Action
-- [Events](./events) — Events emitted by the GLS Action
-- [Common Use Cases](./use-cases) — Example flows for real-world scenarios
-- [Troubleshooting](./troubleshooting) — FAQ and community support
+- [Quick Start](../quick-start) — Create your first shipment in a few steps
+- [Configuration](../configs) — Full list of configuration options and how to get credentials
+- [Functions](../functions) — All available functions with parameter details
+- [Types](../types) — All data types used in the GLS Action
+- [Events](../events) — Events emitted by the GLS Action
+- [Common Use Cases](../use-cases) — Example flows for real-world scenarios
+- [Troubleshooting](../troubleshooting) — FAQ and community support
diff --git 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) for the complete list.
+See [Functions](../functions.md) for the complete list.
 
 ---
 
@@ -63,29 +63,8 @@ A: Check the following:
 
 ---
 
-**Q: I get "Failed to register config definitions" on startup. What does that mean?**
-
-A: This means the action could not register its configuration schema with the Aquila server. Check:
-- The Aquila server is running and healthy
-- The `HERCULES_AUTH_TOKEN` has sufficient permissions
-- The action ID (`HERCULES_ACTION_ID`) is not already registered with a conflicting schema
-
----
-
-**Q: The action shows "SDK connected successfully" but my functions don't appear in Hercules.**
-
-A: Wait a few seconds — registration can take a moment. Then refresh the Hercules UI. If functions still don't appear, check that the action's `HERCULES_ACTION_ID` matches what is configured in Hercules.
-
----
-
 ### Authentication & API errors
 
-**Q: I get a 401 Unauthorized error when the action tries to call the GLS API.**
-
-A: Your `client_id` or `client_secret` is incorrect, or your GLS application does not have the required API scopes. Verify your credentials on the [GLS Developer Portal](https://dev-portal.gls-group.net) and ensure the **ShipIT** scope is enabled.
-
----
-
 **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.
@@ -104,11 +83,6 @@ A: No. Once GLS has scanned the parcel at a depot or delivery vehicle, cancellat
 
 ---
 
-**Q: My token expires frequently. Can I adjust the refresh interval?**
-
-A: The action automatically refreshes tokens 60 seconds before they expire. This is hard-coded and cannot be changed through configuration. GLS OAuth2 tokens typically have a validity of 1 hour.
-
----
 
 ### Labels & printing
 
@@ -212,9 +186,3 @@ Open a pull request against the `main` branch of [code0-tech/centaurus](https://
 | `npm run lint` | Run ESLint |
 | `npm run create-action -- <name>` | Scaffold a new action |
 
-### Code conventions
-
-- All types must use **Zod schemas** with a matching `Schema` suffix (e.g. `AddressSchema` / `Address`)
-- All registered types must have identifiers starting with `GLS_` (for the GLS action)
-- All function definitions must include `name` and `description` in `en-US`
-- Functions that call external APIs must wrap errors in `RuntimeErrorException`
diff --git a/docs/Actions/GLS/types.md b/docs/Actions/GLS/types.md
diff --git a/docs/Guides/installation.md b/docs/Guides/installation.md

Original file line number	Diff line number	Diff line change
@@ -107,4 +107,4 @@ The value must be a valid `GLS_SHIPPER` object:
`107`	`107`	`}`
`108`	`108`	```
`109`	`109`
`110`		`-See [Types — GLS_SHIPPER](./types#GLS_SHIPPER) for the full field reference.`
	`110`	`+See [Types — GLS_SHIPPER](../types/#GLS_SHIPPER) for the full field reference.`