Merge pull request slack-go#1220 from stijndcl/manifests

Add support for manifests and config tokens

examples/manifests/README.md

@@ -0,0 +1,38 @@
+# Manifest examples
+
+This example shows how to interact with the
+new [manifest endpoints](https://api.slack.com/reference/manifests#manifest_apis). These endpoints require a special set
+of tokens called `configuration tokens`. Refer to
+the [relevant documentation](https://api.slack.com/authentication/config-tokens) for how to create these tokens.
+
+For examples on how to use configuration tokens, see the [tokens example](../tokens).
+
+## Usage info
+
+The manifest endpoints allow you to configure your application programmatically instead of manually creating
+a `manifest.yaml` file and uploading it on your Slack application's dashboard.
+
+A manifest should follow a specific structure and has a handful of required fields. These are describe in
+the [manifest documentation](https://api.slack.com/reference/manifests#fields), but Slack additionally returns very
+informative error messages for malformed templates to help you pin down what the issue is. The library itself does not
+attempt to perform any form of validation on your manifest.
+
+**Note that each configuration token may only be used once before being invalidated. Again refer to the tokens example
+for more information.**
+
+## Available methods
+
+- ``Slack.CreateManifest()``
+- ``Slack.DeleteManifest()``
+- ``Slack.ExportManifest()``
+- ``Slack.UpdateManifest()``
+
+## Example details
+
+The example code here only shows how to _update_ an application using a manifest. The other available methods are either
+identical in usage or trivial to use, so no full example is provided for them.
+
+The example doesn't rotate the configuration tokens after updating the manifest. **You should almost always do this**.
+Your access token is invalidated after sending a request, and rotating your tokens will allow you to make another
+request in the future. This example does not do this explicitly as it would just repeat the tokens example. For sake of
+simplicity, it only focuses on the manifest part.

examples/manifests/manifest.go

@@ -0,0 +1,45 @@
+package manifests
+
+import (
+	"fmt"
+	"github.com/slack-go/slack"
+)
+
+// createManifest programmatically creates a Slack app manifest
+func createManifest() *slack.Manifest {
+	return &slack.Manifest{
+		Display: slack.Display{
+			Name: "Your Application",
+		},
+		// ... other configuration here
+	}
+}
+
+func main() {
+	api := slack.New(
+		"YOUR_TOKEN_HERE",
+		// You may choose to provide your access token when creating your Slack client
+		// or when invoking the method calls
+		slack.OptionConfigToken("YOUR_CONFIG_ACCESS_TOKEN_HERE"),
+	)
+
+	// Create a new Manifest object
+	manifest := createManifest()
+
+	// Update your application using the new manifest
+	// You may pass your token as a parameter here as well, if you didn't do it above
+	response, err := api.UpdateManifest(manifest, "", "YOUR_APP_ID_HERE")
+	if err != nil {
+		fmt.Printf("error updating Slack application: %v\n", err)
+		return
+	}
+
+	if !response.Ok {
+		fmt.Printf("unable to update Slack application: %v\n", response.Errors)
+	}
+
+	fmt.Println("successfully updated Slack application")
+
+	// The access token is now invalid, so it should be rotated for future use
+	// Refer to the examples about tokens for more details
+}

examples/tokens/README.md

@@ -0,0 +1,10 @@
+# Tokens examples
+
+The refresh token endpoint can be used to update
+your [configuration tokenset](https://api.slack.com/authentication/config-tokens). These tokens may only be used **once
+** before being invalidated, and are only valid for up to **12 hours**.
+
+Once a token has been used, or before it expires, you can use the `RotateTokens()` method to obtain a fresh set to use
+for the next request. Depending on your use-case you may want to store these somewhere for a future run, so they are
+only returned by the method call. If you wish to update the tokens inside the active Slack client, this can be done
+using `UpdateConfigTokens()`.

examples/tokens/tokens.go

@@ -0,0 +1,33 @@
+package tokens
+
+import (
+	"fmt"
+	"github.com/slack-go/slack"
+)
+
+func main() {
+	api := slack.New(
+		"YOUR_TOKEN_HERE",
+		// You may choose to provide your config tokens when creating your Slack client
+		// or when invoking the method calls
+		slack.OptionConfigToken("YOUR_CONFIG_ACCESS_TOKEN_HERE"),
+		slack.OptionConfigRefreshToken("YOUR_REFRESH_TOKEN_HERE"),
+	)
+
+	// Obtain a fresh set of tokens
+	// You may pass your tokens as a parameter here as well, if you didn't do it above
+	freshTokens, err := api.RotateTokens("", "")
+	if err != nil {
+		fmt.Printf("error rotating tokens: %v\n", err)
+		return
+	}
+
+	fmt.Printf("new access token: %s\n", freshTokens.Token)
+	fmt.Printf("new refresh token: %s\n", freshTokens.RefreshToken)
+	fmt.Printf("new tokenset expires at: %d\n", freshTokens.ExpiresAt)
+
+	// Optionally: update the tokens inside the running Slack client
+	// This isn't necessary if you restart the application after storing the tokens elsewhere,
+	// or pass them as parameters to RotateTokens() explicitly
+	api.UpdateConfigTokens(freshTokens)
+}