Set project-specific user agent, offer override

- Apply project-speciifc default user agent to override the
  Go default of `Go-http-client/1.1`
  - set version based on when this project first diverged from
    the parent project
- Offer override for client code
- Add brief example to illustrate setting custom user agent

refs GH-134

README.md

@@ -27,6 +27,7 @@ A package to send messages to Microsoft Teams (channels)
     - [How to create a webhook URL (Connector)](#how-to-create-a-webhook-url-connector)
   - [Examples](#examples)
     - [Basic](#basic)
+    - [Set custom user agent](#set-custom-user-agent)
     - [Add an Action](#add-an-action)
     - [Disable webhook URL prefix validation](#disable-webhook-url-prefix-validation)
     - [Enable custom patterns' validation](#enable-custom-patterns-validation)
@@ -70,6 +71,7 @@ information.
 - Configurable timeouts
 - Configurable retry support
 - Support for overriding the default `http.Client`
+- Support for overriding default project-specific user agent
 
 ## Project Status
 
@@ -185,6 +187,12 @@ This is an example of a simple client application which uses this library.
 
 File: [basic](./examples/basic/main.go)
 
+#### Set custom user agent
+
+This example illustrates setting a custom user agent.
+
+File: [custom-user-agent](./examples/custom-user-agent/main.go)
+
 #### Add an Action
 
 This example illustrates adding an [`OpenUri Action`][msgcard-ref-actions] to

doc.go

@@ -35,6 +35,8 @@ FEATURES
 
 • Support for overriding the default http.Client
 
+• Support for overriding the default project-specific user agent
+
 
 USAGE
 

examples/custom-user-agent/main.go

@@ -0,0 +1,52 @@
+// Copyright 2021 Adam Chalkley
+//
+// https://github.com/atc0005/go-teams-notify
+//
+// Licensed under the MIT License. See LICENSE file in the project root for
+// full license information.
+
+/*
+
+This is an example of a simple client application which uses this library.
+
+Of note:
+
+- default timeout
+- custom user agent
+- package-level logging is disabled by default
+- validation of known webhook URL prefixes is *enabled*
+- simple message submitted to Microsoft Teams consisting of formatted body and
+  title
+
+*/
+
+package main
+
+import (
+	goteamsnotify "github.com/atc0005/go-teams-notify/v2"
+)
+
+func main() {
+	_ = sendTheMessage()
+}
+
+func sendTheMessage() error {
+	// init the client
+	mstClient := goteamsnotify.NewClient()
+
+	// override the project-specific default user agent
+	mstClient.SetUserAgent("go-teams-notify-example/1.0")
+
+	// setup webhook url
+	webhookUrl := "https://outlook.office.com/webhook/YOUR_WEBHOOK_URL_OF_TEAMS_CHANNEL"
+
+	// setup message card
+	msgCard := goteamsnotify.NewMessageCard()
+	msgCard.Title = "Hello world"
+	msgCard.Text = "Here are some examples of formatted stuff like " +
+		"<br> * this list itself  <br> * **bold** <br> * *italic* <br> * ***bolditalic***"
+	msgCard.ThemeColor = "#DF813D"
+
+	// send
+	return mstClient.Send(webhookUrl, msgCard)
+}

send.go

@@ -69,6 +69,14 @@ const ExpectedWebhookURLResponseText string = "1"
 // before it times out and is cancelled.
 const DefaultWebhookSendTimeout = 5 * time.Second
 
+// DefaultUserAgent is the project-specific user agent used when submitting
+// messages unless overridden by client code. This replaces the Go default
+// user agent value of "Go-http-client/1.1".
+//
+// The major.minor numbers reflect when this project first diverged from the
+// "upstream" or parent project.
+const DefaultUserAgent string = "go-teams-notify/2.2"
+
 // ErrWebhookURLUnexpected is returned when a provided webhook URL does
 // not match a set of confirmed webhook URL patterns.
 var ErrWebhookURLUnexpected = errors.New("webhook URL does not match one of expected patterns")
@@ -90,13 +98,15 @@ type API interface {
 	SendWithContext(ctx context.Context, webhookURL string, webhookMessage MessageCard) error
 	SendWithRetry(ctx context.Context, webhookURL string, webhookMessage MessageCard, retries int, retriesDelay int) error
 	SetHTTPClient(httpClient *http.Client) API
+	SetUserAgent(userAgent string) API
 	SkipWebhookURLValidationOnSend(skip bool) API
 	AddWebhookURLValidationPatterns(patterns ...string) API
 	ValidateWebhook(webhookURL string) error
 }
 
 type teamsClient struct {
 	httpClient                   *http.Client
+	userAgent                    string
 	webhookURLValidationPatterns []string
 	skipWebhookURLValidation     bool
 }
@@ -142,6 +152,14 @@ func (c *teamsClient) SetHTTPClient(httpClient *http.Client) API {
 	return c
 }
 
+// SetUserAgent accepts a custom user agent string. This custom user agent is
+// used when submitting messages to Microsoft Teams.
+func (c *teamsClient) SetUserAgent(userAgent string) API {
+	c.userAgent = userAgent
+
+	return c
+}
+
 func (c *teamsClient) AddWebhookURLValidationPatterns(patterns ...string) API {
 	c.webhookURLValidationPatterns = append(c.webhookURLValidationPatterns, patterns...)
 	return c
@@ -190,6 +208,14 @@ func (c teamsClient) SendWithContext(ctx context.Context, webhookURL string, web
 	req, _ := http.NewRequestWithContext(ctx, http.MethodPost, webhookURL, webhookMessageBuffer)
 	req.Header.Add("Content-Type", "application/json;charset=utf-8")
 
+	// If provided, override the project-specific user agent with custom value.
+	switch {
+	case c.userAgent != "":
+		req.Header.Set("User-Agent", c.userAgent)
+	default:
+		req.Header.Set("User-Agent", DefaultUserAgent)
+	}
+
 	// do the request
 	res, err := c.httpClient.Do(req)
 	if err != nil {