Skip to content

Add comprehensive GLS Action documentation#1

Merged
Knerio merged 3 commits intomainfrom
copilot/enhance-docs-and-add-more
Mar 19, 2026
Merged

Add comprehensive GLS Action documentation#1
Knerio merged 3 commits intomainfrom
copilot/enhance-docs-and-add-more

Conversation

Copy link
Contributor

Copilot AI commented Mar 19, 2026

The existing docs were minimal stubs. This PR adds full reference documentation covering all GLS Action capabilities, with correct conceptual framing of the Hercules platform primitives (events vs functions).

New pages

  • overview.md — What the action does, prerequisites (Aquila + GLS portal credentials), architecture and data flow diagrams
  • quick-start.md — Hello World flow: build address → shipment unit → printing options → create shipment → consume response
  • events.md — Correctly documents events as action-initiated triggers dispatched to Aquila (via registerFlowTypes + dispatchEvent) that start flows, not function outputs. GLS currently has no events; planned ones (gls.shipment.arrived, .delivered, .failed, .returned) are documented with their expected payload shapes and SDK registration pattern
  • functions.md — All 26 functions (5 builders, 14 shipment creators, 7 API ops) with signatures, parameter tables, constraints, and data flow diagrams
  • types.md — All 24 registered types with field-level reference tables, constraint annotations, and a type dependency diagram
  • use-cases.md — 8 end-to-end flow examples: standard delivery, validate-then-create, return shipment, identity-verified delivery, end-of-day reconciliation, label reprint, allowed services query, Saturday express
  • troubleshooting.md — FAQ grouped by area, error code reference table, contribution guide
  • meta.json — Navigation order for the GLS docs section

Improved pages

  • README.md — Rewritten: available actions table, base ENV vars, quick start steps, doc links
  • docs/index.mdx — Prerequisites, actions table, quick links hub
  • docs/Guides/installation.md — Full step-by-step replacing the stub: ENV table, example .env, verification, update and troubleshooting steps
  • docs/Actions/GLS/configs.md — Full config reference, step-by-step GLS Developer Portal credential guide, OAuth2 token flow diagram, default shipper explanation

Key conceptual correction

The events page was initially drafted incorrectly (treating function return values as events). Corrected: events flow action → Aquila → flow, not the other way around.

External trigger (webhook / poll)
    │
    ▼
GLS Action
    │  sdk.dispatchEvent("gls.shipment.arrived", projectId, payload)
    ▼
Aquila → triggers subscribed flows

⚡ Quickly spin up Copilot coding agent tasks from anywhere on your macOS or Windows machine with Raycast.

Co-authored-by: Knerio <96529060+Knerio@users.noreply.github.com>
Copilot AI changed the title [WIP] Update documentation for better clarity and coverage Add comprehensive GLS Action documentation Mar 19, 2026
Copilot AI requested a review from Knerio March 19, 2026 12:29
@Knerio Knerio marked this pull request as ready for review March 19, 2026 12:51
@Knerio Knerio merged commit 05d30cc into main Mar 19, 2026
1 check passed
@Knerio Knerio deleted the copilot/enhance-docs-and-add-more branch March 19, 2026 12:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants