Skip to content

Commit 05d30cc

Browse files
KnerioKnerio
authored
Merge pull request #1 from code0-tech/copilot/enhance-docs-and-add-more
Add comprehensive GLS Action documentation
2 parents 15367bf + fd0ea43 commit 05d30cc

14 files changed

Lines changed: 2239 additions & 45 deletions

File tree

‎README.md‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,47 @@
11
# centaurus
2-
The "central" place for all actions
32

4-
# ENV
3+
The "central" place for all actions — a monorepo containing integrations provided by [code0](https://github.com/code0-tech) for the **Hercules** automation platform.
4+
5+
## Available Actions
6+
7+
| Action | Description |
8+
|--------|-------------|
9+
| [GLS](docs/Actions/GLS/overview.md) | GLS ShipIT integration for creating and managing shipments |
10+
11+
## ENV
12+
13+
All actions share the following base environment variables, which connect them to the Hercules/Aquila infrastructure:
14+
515
| ENV Variable | Description | Default Value |
616
|------------------------|------------------------------------------------|---------------------|
717
| `HERCULES_AUTH_TOKEN` | Authentication token for connecting to Aquila. | `""` (empty string) |
818
| `HERCULES_AQUILA_URL` | URL of the Aquila server to connect to. | `"localhost:50051"` |
919
| `HERCULES_ACTION_ID` | Identifier for the action being registered. | `"<action-name>"` |
1020
| `HERCULES_SDK_VERSION` | Version of the Hercules SDK being used. | `"0.0.0"` |
21+
22+
## Quick Start
23+
24+
1. Clone the repository
25+
2. Navigate to the action directory: `cd actions/<action-name>`
26+
3. Copy the example env file: `cp .example.env .env`
27+
4. Fill in your credentials and Hercules connection details in `.env`
28+
5. Start the action: `docker compose up -d`
29+
30+
See the [Installation Guide](docs/Guides/installation.md) for detailed steps.
31+
32+
## Documentation
33+
34+
Full documentation is located in the [`docs/`](docs/) folder:
35+
36+
- [Installation Guide](docs/Guides/installation.md)
37+
- [GLS Action Overview](docs/Actions/GLS/overview.md)
38+
- [GLS Configuration](docs/Actions/GLS/configs.md)
39+
- [GLS Functions](docs/Actions/GLS/functions.md)
40+
- [GLS Types](docs/Actions/GLS/types.md)
41+
- [GLS Events](docs/Actions/GLS/events.md)
42+
- [Common Use Cases](docs/Actions/GLS/use-cases.md)
43+
- [Troubleshooting & Community Support](docs/Actions/GLS/troubleshooting.md)
44+
45+
## Contributing
46+
47+
Contributions are welcome! See [Troubleshooting & Community Support](docs/Actions/GLS/troubleshooting.md#contributing) for guidelines.

‎actions/gls-action/src/helpers.ts‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,7 @@ export function transformValidateShipmentRequestDataToInternalFormat(data: Valid
245245
Shipment: {
246246
...data.Shipment,
247247
Middleware: "CodeZeroviaGLS",
248-
Shipper: getShipper(data.Shipment.Shipper, context, contactID),
248+
Shipper: getShipper(context, contactID, data.Shipment.Shipper),
249249
Service: InternalShipmentServiceSchema.parse(data.Shipment.Service),
250250
ShipmentUnit: InternalShipmentUnitSchema.parse(data.Shipment.ShipmentUnit)
251251
}
@@ -258,27 +258,31 @@ function transformShipmentRequestDataToInternalFormat(data: ShipmentRequestData,
258258
Shipment: {
259259
...data.Shipment,
260260
Middleware: "CodeZeroviaGLS",
261-
Shipper: getShipper(data.Shipment.Shipper, context, contactID),
261+
Shipper: getShipper(context, contactID, data.Shipment.Shipper),
262262
Service: InternalShipmentServiceSchema.parse(data.Shipment.Service),
263263
ShipmentUnit: InternalShipmentUnitSchema.parse(data.Shipment.ShipmentUnit)
264264
}
265265
}
266266
}
267267

268-
function getShipper(shipper: Shipper, context: HerculesFunctionContext | undefined, contactID: string | undefined): InternalShipper {
268+
function getShipper(context: HerculesFunctionContext | undefined, contactID: string | undefined, shipper?: Shipper): InternalShipper {
269269
const configShipper = context?.matchedConfig.findConfig("shipper") as Shipper || undefined
270270

271-
if (configShipper) {
272-
return {
273-
...configShipper,
274-
ContactID: contactID
275-
}
276-
} else {
271+
if (!shipper && !configShipper) {
272+
throw new RuntimeErrorException("MISSING_SHIPPER_INFORMATION", "No shipper information provided in shipment data or configuration.")
273+
}
274+
275+
if (shipper) {
277276
return {
278277
...shipper,
279278
ContactID: contactID
280279
}
281280
}
281+
282+
return {
283+
...configShipper,
284+
ContactID: contactID
285+
}
282286
}
283287

284288
export async function postShipmentHelper(context: HerculesFunctionContext, services: ShipmentService, shipment: ShipmentWithoutServices, printingOptions: PrintingOptions, customContent?: CustomContent, returnOptions?: ReturnOptions): Promise<CreateParcelsResponse> {

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,7 @@ export const ShipmentSchema = z.object({
309309
Product: z.enum(["PARCEL", "EXPRESS"]),
310310
ExpressAltDeliveryAllowed: z.boolean().optional(),
311311
Consignee: ConsigneeSchema,
312-
Shipper: ShipperSchema,
312+
Shipper: ShipperSchema.optional(),
313313
Carrier: z.enum(["ROYALMAIL"]).optional(),
314314
ShipmentUnit: ShipmentUnitSchema,
315315
Service: ShipmentServiceSchema,

‎docs/Actions/GLS/configs.md‎

Lines changed: 101 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,110 @@
11
---
22
title: Action Configuration
3+
description: All configuration options for the GLS Action, including how to obtain credentials from the GLS Developer Portal.
34
---
45

5-
The GLS action provides following configurations:
6+
# GLS Action Configuration
67

7-
| Config Name | Description | Type | Required |
8-
|-----------------|------------------------------------------------------------------|-------------|----------|
9-
| contact_id | The contact id used in some requests | string | No |
10-
| client_id | The client id used for auth purposes | string | Yes |
11-
| client_secret | The client secret used for auth purposes | string | Yes |
12-
| ship_it_api_url | Gls provides multiple ship it urls, provide yours | string | No |
13-
| auth_url | Gls provides multiple auth urls, provide yours ending in /token | string | No |
14-
| shipper | And default shipper which is replaced in the request if provided | GLS_SHIPPER | No |
8+
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).
159

10+
---
11+
12+
## Configuration reference
13+
14+
| Config Name | Type | Required | Default | Description |
15+
|-----------------|-------------|----------|---------|-------------|
16+
| `client_id` | string | **Yes** | — | OAuth2 client ID for authenticating with the GLS API |
17+
| `client_secret` | string | **Yes** | — | OAuth2 client secret for authenticating with the GLS API |
18+
| `contact_id` | string | No | `""` | GLS contact ID used in some API requests (see note below) |
19+
| `ship_it_api_url` | string | No | `https://api.gls-group.net/shipit-farm/v1/backend/rs` | GLS ShipIT API base URL |
20+
| `auth_url` | string | No | `https://api.gls-group.net/oauth2/v2/token` | GLS OAuth2 token endpoint — must end in `/token` |
21+
| `shipper` | GLS_SHIPPER | No | — | Default shipper address used when no shipper is provided in the shipment data |
22+
23+
> **`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.
24+
25+
---
26+
27+
## How to obtain your credentials
28+
29+
### Step 1 — Create a GLS Developer account
30+
31+
1. Go to [https://dev-portal.gls-group.net/get-started](https://dev-portal.gls-group.net/get-started)
32+
2. Click **Sign In** and register a new account, or log in with an existing GLS account
33+
3. Complete the registration and verify your email address
34+
35+
### Step 2 — Create an application
36+
37+
1. After logging in, navigate to **My Apps** in the top navigation
38+
2. Click **Create App** (or **New Application**)
39+
3. Fill in the application name and description
40+
4. Select the required API scopes (typically **ShipIT**)
41+
5. Submit the form
42+
43+
### Step 3 — Retrieve your credentials
44+
45+
1. Open the application you just created in **My Apps**
46+
2. Copy the **Client ID** — this is your `client_id`
47+
3. Copy the **Client Secret** — this is your `client_secret`
48+
49+
> Keep the `client_secret` confidential. Do not commit it to source control.
50+
51+
### Step 4 — Get your Contact ID (optional)
52+
53+
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.
54+
55+
---
56+
57+
## API endpoints
58+
59+
GLS provides different API endpoints depending on your region and environment. The defaults point to the global production API:
60+
61+
| Setting | Default URL |
62+
|---------|-------------|
63+
| `ship_it_api_url` | `https://api.gls-group.net/shipit-farm/v1/backend/rs` |
64+
| `auth_url` | `https://api.gls-group.net/oauth2/v2/token` |
65+
66+
If you are using a regional or sandbox endpoint, update these values accordingly. Always ensure `auth_url` ends with `/token`.
67+
68+
---
69+
70+
## Authentication flow
71+
72+
The GLS Action authenticates using **OAuth2 client credentials**:
73+
74+
```
75+
GLS Action
76+
│
77+
├── POST {auth_url}
78+
│ body: grant_type=client_credentials
79+
│ client_id=<your-client-id>
80+
│ client_secret=<your-client-secret>
81+
│
82+
│◄── { access_token, expires_in }
83+
│
84+
└── All subsequent API calls include:
85+
Authorization: Bearer <access_token>
86+
```
87+
88+
Tokens are **cached** and automatically refreshed 60 seconds before they expire. You do not need to manage token lifecycle manually.
89+
90+
---
91+
92+
## Default shipper
93+
94+
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.
1695

17-
For you to receive that credentials you need to follow this guide: https://dev-portal.gls-group.net/get-started#sign-in
96+
The value must be a valid `GLS_SHIPPER` object:
1897

19-
You can receive the client id and secret under "My Apps" after creating one.
98+
```json
99+
{
100+
"Address": {
101+
"Name1": "My Company GmbH",
102+
"CountryCode": "DE",
103+
"City": "Berlin",
104+
"Street": "Hauptstrasse",
105+
"ZIPCode": "10115"
106+
}
107+
}
108+
```
20109

21-
The Contact id needs to be retrieved from GLS support, so you need to contact them and ask for it.
110+
See [Types — GLS_SHIPPER](../types/#GLS_SHIPPER) for the full field reference.

‎docs/Actions/GLS/events.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: GLS Action Events
3+
description: Events emitted by the GLS Action — what they are, how they trigger flows in Aquila, and what future events are planned.
4+
---
5+
6+
# GLS Action Events
7+
8+
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.
9+
10+
---
11+
12+
## Current status
13+
14+
> **The GLS Action does not currently emit any events.**
15+
>
16+
> 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**.
17+
18+
---

0 commit comments

Comments
 (0)