From 221af275ee80dd35c0def0a61c7be48e41b15024 Mon Sep 17 00:00:00 2001
From: Saurabh Nanda <saurabh@vacationlabs.com>
Date: Mon, 23 Sep 2024 08:00:01 +0000
Subject: [PATCH] Exported Servant.Links.addQueryParam

---
 changelog.d/issue-1232       |  9 +++++++++
 servant/src/Servant/Links.hs | 14 ++++++++++++++
 2 files changed, 23 insertions(+)
 create mode 100644 changelog.d/issue-1232

diff --git a/changelog.d/issue-1232 b/changelog.d/issue-1232
new file mode 100644
index 000000000..da55649f5
--- /dev/null
+++ b/changelog.d/issue-1232
@@ -0,0 +1,9 @@
+synopsis: Exported addQueryParam
+packages: servant
+prs: #1785
+issues: #1232
+significance: minor
+description: {
+  `addQueryParams` is required to define custom `HasLink` instances which actually manipulate the
+  generated query params. This function was not exported earlier and now it is.
+}
diff --git a/servant/src/Servant/Links.hs b/servant/src/Servant/Links.hs
index 82c285d9d..2f60ef320 100644
--- a/servant/src/Servant/Links.hs
+++ b/servant/src/Servant/Links.hs
@@ -115,6 +115,8 @@ module Servant.Links (
   , linkSegments
   , linkQueryParams
   , linkFragment
+  , addQueryParam
+  , addSegment
 ) where
 
 import           Data.Kind
@@ -187,6 +189,10 @@ import           Web.HttpApiData
 -- | A safe link datatype.
 -- The only way of constructing a 'Link' is using 'safeLink', which means any
 -- 'Link' is guaranteed to be part of the mentioned API.
+--
+-- NOTE: If you are writing a custom 'HasLink' instance, and need to manipulate
+-- the 'Link' (adding query params or fragments, perhaps), please use the the
+-- 'addQueryParam' and 'addSegment' functions.
 data Link = Link
   { _segments    :: [Escaped]
   , _queryParams :: [Param]
@@ -232,10 +238,18 @@ data Param
 addSegment :: Escaped -> Link -> Link
 addSegment seg l = l { _segments = _segments l <> [seg] }
 
+-- | Add a 'Param' (query param) to a 'Link'
+--
+-- Please use this judiciously from within your custom 'HasLink' instances
+-- to ensure that you don't end-up breaking the safe provided by "safe links"
 addQueryParam :: Param -> Link -> Link
 addQueryParam qp l =
     l { _queryParams = _queryParams l <> [qp] }
 
+-- | Add a 'Fragment' (query param) to a 'Link'
+--
+-- Please use this judiciously from within your custom 'HasLink' instances
+-- to ensure that you don't end-up breaking the safe provided by "safe links"
 addFragment :: Fragment' -> Link -> Link
 addFragment fr l = l { _fragment = fr }