feat: implement storeGroupValue and getGroupValue with unified locator

- API Refactoring: Extracted GroupValueLocator input type to unify parameters for storeGroupValue (mutation) and getGroupValue (query).

- Data Retrieval: Implemented getGroupValue query to allow direct retrieval of JSON values stored in host groups via Zabbix Trapper items.

- Enhanced Logic: Added ZabbixGetGroupValueRequest to fetch latest history values for group-associated items.

- Improved Verification: Updated the regression suite (REG-STORE) to include a full 'Store-Update-Retrieve' verification cycle.

- Documentation:

    - Updated docs/howtos/cookbook.md recipes to use the new locator structure and getGroupValue for verification.

    - Updated sample query files (docs/queries/) with corrected variables and verification queries.

- Tests:

    - Added unit and integration tests for getGroupValue.

    - Updated existing tests to match the refactored storeGroupValue schema.

- Verification: Verified 100% pass rate for all 16 regression steps and all unit/integration tests.

schema/api_commons.graphql

@@ -159,3 +159,27 @@ enum SortOrder {
     "Deliver values in descending order"
     desc
 }
+
+"""
+Input for locating a specific value stored within a host group.
+Used by both retrieval queries and storage mutations.
+"""
+input GroupValueLocator {
+    """ID of the target host group (either groupid or groupName is required)."""
+    groupid: Int
+    """Name of the target host group (either groupid or groupName is required)."""
+    groupName: String
+    """Name of the host to store/retrieve the value (optional). If not provided, valueType is used to find or create a storage host."""
+    host: String
+    """
+    The value for the "valueType" tag of the storage host. 
+    Mandatory if no host is provided. Used to identify the host within the group.
+    """
+    valueType: String
+    """Item ID if an existing item should be used."""
+    itemid: Int
+    """The technical key of the item."""
+    key: String!
+    """The visible name of the item (optional)."""
+    name: String
+}

schema/mutations.graphql

@@ -143,6 +143,30 @@ type Mutation {
         values: [HistoryPushInput!]!
     ): HistoryPushResponse
 
+    """
+    Store JSON object (e.g. config value) and assign it to a host group by groupid or groupName.
+    If both groupid or groupName are unset an error will be returned and the dataset will not be stored.
+
+    If host is provided the corresponding host will be looked up and the value will be pushed to
+    an item of this host with the corresponding key - if such an item does not exist it will be created,
+    if it exists it must be a ZABBIX_TRAP item, otherwise an error is returned. If a name is specified it will be
+    set as item name.
+
+    If no host is provided the field valueType is mandatory - the hosts of the specified group will
+    be looked up for a host having a corresponding tag "valueType" matching to the specified value.
+    If multiple hosts exist with this tag and this group, an error will be thrown.
+    If no hosts exist with this tag and this group a new host will be created and the tag and the group will be assigned.
+
+    Return value: If no error occurs, a hostid and an itemid will be returned.
+
+    Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
+    """
+    storeGroupValue(
+        """The locator for the group value."""
+        locator: GroupValueLocator!
+        """The JSON object to store."""
+        value: JSONObject!): HistoryPushData
+
     """
     Runs a smoketest: creates a template, links a host, verifies it, and cleans up.
     """
@@ -161,6 +185,12 @@ type Mutation {
     runAllRegressionTests: SmoketestResponse!
 }
 
+input Tag {
+    tag: String!,
+    value: String!
+}
+
+
 """
 Response object for the smoketest operation.
 """

schema/queries.graphql

@@ -169,5 +169,15 @@ type Query {
         """Wildcard name pattern for filtering template groups."""
         name_pattern: String
     ): [HostGroup]
+
+    """
+    Retrieves the last value stored with `storeGroupValue`.
+    
+    Authentication: Requires `zbx_session` cookie or `zabbix-auth-token` header.
+    """
+    getGroupValue(
+        """Parameters to locate the stored value."""
+        locator: GroupValueLocator!
+    ): JSONObject
 }