From e41497e9d2caebeabcb869d3b61b0dfdb6367949 Mon Sep 17 00:00:00 2001
From: Kjetil Hope Tufteland <kjetil@clarify.io>
Date: Tue, 6 May 2025 21:05:15 +0200
Subject: [PATCH] clarifyx: added method to annotate signals from admin
 namespace

---
 examples/signals_annotate/main.go | 50 ++++++++++++++++++++++++++++
 views/signal_annotate.go          | 20 ++++++++++++
 x/admin.go                        | 54 +++++++++++++++++++++++++++++++
 x/clarifyx.go                     |  1 +
 4 files changed, 125 insertions(+)
 create mode 100644 examples/signals_annotate/main.go
 create mode 100644 views/signal_annotate.go
 create mode 100644 x/admin.go

diff --git a/examples/signals_annotate/main.go b/examples/signals_annotate/main.go
new file mode 100644
index 0000000..b71f318
--- /dev/null
+++ b/examples/signals_annotate/main.go
@@ -0,0 +1,50 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+
+	clarify "github.com/clarify/clarify-go"
+
+	"github.com/clarify/clarify-go/views"
+	clarifyx "github.com/clarify/clarify-go/x"
+)
+
+func main() {
+	// To select or publish signals, you must grant the integration access to
+	// the "admin" namespace in the Clarify admin panel.
+	creds, err := clarify.CredentialsFromFile("clarify-credentials.json")
+	if err != nil {
+		panic(err)
+	}
+
+	ctx := context.Background()
+	client := creds.Client(ctx)
+	xclient := clarifyx.Upgrade(client)
+
+	// For this example, the signals we want to select are created by the same
+	// integration that we are using to select them. Note that this isn't a
+	// requirement; for production cases, you may want this integration ID to be
+	// configured to be something else.
+	integrationID := creds.Integration
+	signalID := "cl1d4kobi2aq0ttkc4b0"
+
+	data := []views.SignalAnnotate{{
+		ID: signalID,
+		Annotations: map[string]string{
+			"obviously-this-blue-part-here": "is-the-land",
+			"i-ve-made-a-huge-mistake":      "", // Empty values deletes the annotation
+		},
+	}}
+
+	result, err := xclient.Admin().Signals().Annotate(integrationID, data).Do(ctx)
+	if err != nil {
+		panic(err)
+	}
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetIndent("", "  ")
+	if err := enc.Encode(result); err != nil {
+		panic(err)
+	}
+}
diff --git a/views/signal_annotate.go b/views/signal_annotate.go
new file mode 100644
index 0000000..2849eb9
--- /dev/null
+++ b/views/signal_annotate.go
@@ -0,0 +1,20 @@
+// Copyright 2025 Searis AS
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package views
+
+type SignalAnnotate struct {
+	ID          string            `json:"id"`
+	Annotations map[string]string `json:"annotations"`
+}
diff --git a/x/admin.go b/x/admin.go
new file mode 100644
index 0000000..1464524
--- /dev/null
+++ b/x/admin.go
@@ -0,0 +1,54 @@
+// Copyright 2025 Searis AS
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package clarifyx
+
+import (
+	"github.com/clarify/clarify-go/internal/request"
+	"github.com/clarify/clarify-go/views"
+)
+
+type AdminSignals struct {
+	AdminNamespace
+}
+
+func (ns AdminNamespace) Signals() AdminSignals {
+	return AdminSignals{AdminNamespace: ns}
+}
+
+// Annotate returns a new request for publishing signals as items.
+func (s AdminSignals) Annotate(integration string, data []views.SignalAnnotate) SignalsAnnotateRequest {
+	return methodSignalsAnnotate.NewRequest(s.Handler(),
+		paramIntegration.Value(integration),
+		paramData.Value(data),
+		paramFormat.Value(views.SelectionFormat{
+			DataAsArray:         true,
+			GroupIncludedByType: true,
+		}),
+	)
+}
+
+type (
+	// SignalsAnnotateRequest describe an initialized admin.signals.annotate RPC
+	// request with access to a request handler.
+	SignalsAnnotateRequest = request.Request[SignalsAnnotateResult]
+
+	// SignalsAnnotateResult describe the result format for a SignalsAnnotateRequest.
+	SignalsAnnotateResult = views.Selection[[]views.Signal, views.SignalInclude]
+)
+
+var methodSignalsAnnotate = request.Method[SignalsAnnotateResult]{
+	APIVersion: apiVersionExperimental,
+	Method:     "admin.signals.annotate",
+}
diff --git a/x/clarifyx.go b/x/clarifyx.go
index 5076f88..b106e78 100644
--- a/x/clarifyx.go
+++ b/x/clarifyx.go
@@ -29,6 +29,7 @@ const (
 
 	paramFormat      jsonrpc.ParamName = "format"
 	paramIntegration jsonrpc.ParamName = "integration"
+	paramData        jsonrpc.ParamName = "data"
 	paramItem        jsonrpc.ParamName = "item"
 	paramQuery       jsonrpc.ParamName = "query"
 )