Skip to content

Commit 6e233a6

Browse files
KnerioKnerio
authored
Merge pull request #8 from code0-tech/generate-docs
Generative docs
2 parents 1c5b51b + 1ed3951 commit 6e233a6

53 files changed

Lines changed: 5511 additions & 1219 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/test.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,10 @@ jobs:
1717
- run: npm run build
1818
- run: npm run lint
1919
- run: npm run test
20+
- name: Validate generated documentation
21+
run: |
22+
npm run generate:docs
23+
if ! git diff --quiet; then
24+
git --no-pager diff
25+
exit 1
26+
fi

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Full documentation is located in the [`docs/`](docs/) folder:
3737
- [GLS Action Overview](docs/Actions/GLS/overview.md)
3838
- [GLS Configuration](docs/Actions/GLS/configs.md)
3939
- [GLS Functions](docs/Actions/GLS/functions.md)
40-
- [GLS Types](docs/Actions/GLS/types.md)
40+
- [GLS Types](docs/Actions/GLS/types.mdx)
4141
- [GLS Events](docs/Actions/GLS/events.md)
4242
- [Common Use Cases](docs/Actions/GLS/use-cases.md)
4343
- [Troubleshooting & Community Support](docs/Actions/GLS/troubleshooting.md)

‎actions/gls-action/package.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@
99
"build": "vite build",
1010
"lint": "eslint .",
1111
"test": "vitest run",
12-
"start": "node dist/main.js"
12+
"start": "node dist/main.js",
13+
"generate:docs": "npm run build && node dist/generateDocs.js"
14+
},
15+
"dependencies": {
16+
"ts-morph": "^27.0.2"
1317
}
1418
}

‎actions/gls-action/scripts/generateDocs.ts‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import {runStandardActionDocs, StandardActionDocsConfig} from "../../../src/standardActionDocs"
2+
import {loadAllDefinitions} from "../src/helpers";
3+
4+
export function createGlsDocsConfig(): StandardActionDocsConfig {
5+
return {
6+
actionName: "GLS",
7+
typePrefix: "GLS_",
8+
typesOutputPath: "../../docs/Actions/GLS/types.mdx",
9+
functionsOutputPath: "../../docs/Actions/GLS/functions.mdx",
10+
loadAllDefinitions,
11+
typeLinkOverrides: {
12+
GLS_SHIPMENT_UNIT_SERVICE: "GLS_SHIPMENT_UNIT$Service",
13+
},
14+
typesCopy: {
15+
title: "Datatypes",
16+
description: "All data types registered by the GLS Action.",
17+
heading: "GLS Action Types",
18+
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.`,
19+
},
20+
functionsCopy: {
21+
title: "Functions",
22+
description: "All functions registered by the GLS Action.",
23+
intro: `The GLS Action exposes functions grouped into three categories:
24+
25+
- **Builder functions** — Construct data objects (no API call)
26+
- **Shipment functions** — Create different types of GLS shipments (calls GLS API)
27+
- **API functions** — Query or modify shipments (calls GLS API)`,
28+
},
29+
functionGroups: [
30+
{
31+
heading: "Builder functions",
32+
modules: import.meta.glob("../src/functions/utils/*.ts"),
33+
},
34+
{
35+
heading: "Shipment functions",
36+
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\`.
37+
38+
**Common parameters for all shipment functions:**
39+
40+
| Parameter | Type | Required | Description |
41+
|-------------------|-------------------------------|----------|----------------------------------------------------|
42+
| \`shipment\` | GLS_SHIPMENT_WITHOUT_SERVICES | **Yes** | Shipment data (consignee, shipper, units, product) |
43+
| \`printingOptions\` | GLS_PRINTING_OPTIONS | **Yes** | Label format settings |
44+
| \`returnOptions\` | GLS_RETURN_OPTIONS | No | Whether to return print data and routing info |
45+
| \`customContent\` | GLS_CUSTOM_CONTENT | No | Custom logo and barcode settings |
46+
47+
---`,
48+
modules: import.meta.glob("../src/functions/services/*.ts"),
49+
},
50+
{
51+
heading: "API functions",
52+
modules: import.meta.glob("../src/functions/*.ts"),
53+
},
54+
],
55+
}
56+
}
57+
58+
await runStandardActionDocs(createGlsDocsConfig())

‎actions/gls-action/src/functions/cancelShipment.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,18 @@ export default (sdk: ActionSdk) => {
77
{
88
definition: {
99
runtimeName: "cancelShipment",
10+
documentation: [
11+
{
12+
code: "en-US",
13+
content: "Cancels an existing shipment by its Track ID. Only possible if the parcel has not yet been scanned."
14+
}
15+
],
16+
displayMessage: [
17+
{
18+
code: "en-US",
19+
content: "Cancel shipment"
20+
}
21+
],
1022
name: [
1123
{
1224
code: "en-US",
@@ -16,7 +28,7 @@ export default (sdk: ActionSdk) => {
1628
description: [
1729
{
1830
code: "en-US",
19-
content: "Cancels a GLS shipment.",
31+
content: "Cancels an existing shipment by its Track ID. Only possible if the parcel has not yet been scanned.",
2032
}
2133
],
2234
signature: "(data: GLS_CANCEL_SHIPMENT_REQUEST_DATA): GLS_CANCEL_SHIPMENT_RESPONSE_DATA",

‎actions/gls-action/src/functions/getAllowedServices.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,18 @@ export default (sdk: ActionSdk) => {
1212
{
1313
definition: {
1414
runtimeName: "getAllowedServices",
15+
documentation: [
16+
{
17+
code: "en-US",
18+
content: "Returns the GLS services available for a given origin/destination country and ZIP code combination."
19+
}
20+
],
21+
displayMessage: [
22+
{
23+
code: "en-US",
24+
content: "Get allowed services"
25+
}
26+
],
1527
name: [
1628
{
1729
code: "en-US",
@@ -21,7 +33,7 @@ export default (sdk: ActionSdk) => {
2133
description: [
2234
{
2335
code: "en-US",
24-
content: "Returns the allowed GLS services for a given set of parameters.",
36+
content: "Returns the GLS services available for a given origin/destination country and ZIP code combination.",
2537
}
2638
],
2739
signature: "(data: GLS_ALLOWED_SERVICES_REQUEST_DATA): GLS_ALLOWED_SERVICES_RESPONSE_DATA",

‎actions/gls-action/src/functions/getEndOfDayReport.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,18 @@ export default (sdk: ActionSdk) => {
88
{
99
definition: {
1010
runtimeName: "getEndOfDayReport",
11+
documentation: [
12+
{
13+
code: "en-US",
14+
content: "Retrieves all shipments dispatched on a given date. Useful for reconciliation and end-of-day processing."
15+
}
16+
],
17+
displayMessage: [
18+
{
19+
code: "en-US",
20+
content: "Get end of day report"
21+
}
22+
],
1123
name: [
1224
{
1325
code: "en-US",
@@ -17,7 +29,7 @@ export default (sdk: ActionSdk) => {
1729
description: [
1830
{
1931
code: "en-US",
20-
content: "Returns the GLS end of day report.",
32+
content: "Retrieves all shipments dispatched on a given date. Useful for reconciliation and end-of-day processing.",
2133
}
2234
],
2335
signature: "(data: GLS_END_OF_DAY_REQUEST_DATA): GLS_END_OF_DAY_RESPONSE_DATA",

‎actions/gls-action/src/functions/reprintParcel.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,18 @@ export default (sdk: ActionSdk) => {
1212
{
1313
definition: {
1414
runtimeName: "reprintParcel",
15+
documentation: [
16+
{
17+
code: "en-US",
18+
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."
19+
}
20+
],
21+
displayMessage: [
22+
{
23+
code: "en-US",
24+
content: "Reprint parcel"
25+
}
26+
],
1527
name: [
1628
{
1729
code: "en-US",
@@ -21,7 +33,7 @@ export default (sdk: ActionSdk) => {
2133
description: [
2234
{
2335
code: "en-US",
24-
content: "Reprints the labels for a GLS parcel.",
36+
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.",
2537
}
2638
],
2739
signature: "(data: GLS_REPRINT_PARCEL_REQUEST_DATA): GLS_REPRINT_PARCEL_RESPONSE_DATA",

‎actions/gls-action/src/functions/services/createAddresseeOnlyShipment.ts‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,18 @@ export default (sdk: ActionSdk) => {
1515
{
1616
definition: {
1717
runtimeName: "createAddresseeOnlyShipment",
18+
documentation: [
19+
{
20+
code: "en-US",
21+
content: "Creates a shipment that can only be delivered to the named addressee (no neighbor delivery)."
22+
}
23+
],
24+
displayMessage: [
25+
{
26+
code: "en-US",
27+
content: "Create addressee only shipment"
28+
}
29+
],
1830
name: [
1931
{
2032
code: "en-US",
@@ -24,7 +36,7 @@ export default (sdk: ActionSdk) => {
2436
description: [
2537
{
2638
code: "en-US",
27-
content: "Creates a GLS addressee only shipment.",
39+
content: "Creates a shipment that can only be delivered to the named addressee (no neighbor delivery).",
2840
}
2941
],
3042
signature: `(${DEFAULT_SIGNATURE_FOR_SERVICES}): GLS_CREATE_PARCELS_RESPONSE`,
@@ -44,4 +56,5 @@ export default (sdk: ActionSdk) => {
4456
}
4557
},
4658
)
47-
}
59+
}
60+

‎actions/gls-action/src/functions/services/createDeliveryAtWorkShipment.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,18 @@ export default (sdk: ActionSdk) => {
1515
{
1616
definition: {
1717
runtimeName: "createDeliveryAtWorkShipment",
18+
documentation: [
19+
{
20+
code: "en-US",
21+
content: "Delivers a parcel to a specific location within a workplace (building, floor, room)."
22+
}
23+
],
24+
displayMessage: [
25+
{
26+
code: "en-US",
27+
content: "Create delivery at work shipment"
28+
}
29+
],
1830
name: [
1931
{
2032
code: "en-US",
@@ -24,7 +36,7 @@ export default (sdk: ActionSdk) => {
2436
description: [
2537
{
2638
code: "en-US",
27-
content: "Creates a GLS delivery at work shipment.",
39+
content: "Delivers a parcel to a specific location within a workplace (building, floor, room).",
2840
}
2941
],
3042
signature: `(recipientName: string, building: string, floor: number, ${DEFAULT_SIGNATURE_FOR_SERVICES}, alternateRecipientName?: string, room?: number, phonenumber?: string): GLS_CREATE_PARCELS_RESPONSE`,

0 commit comments

Comments
 (0)