feat: update for user-provided identifiers, update deps, etc

Author: danielgtaylor

README.md

@@ -27,7 +27,7 @@ This command generates static content into the `build` directory and can be serv
 ## Deployment
 
 ```console
-GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+GIT_USER=<Your GitHub username> USE_SSH=true DEPLOYMENT_BRANCH=main yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/cli.mdx

@@ -6,17 +6,29 @@ sidebar_label: Download CLI
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
+import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
 
-iStreamPlanet's APIs implement OpenAPI 3 descriptions which are publicly linked via [RFC 8631](https://tools.ietf.org/html/rfc8631) `service-desc` link relation headers and auto-discovery for [CLI configuration](https://rest.sh/#/openapi?id=autoconfiguration) via `x-cli-config` extension. This means you can use any client which understands these features to interact with our APIs.
-
-Since the client is generated from API-provided descriptions rather than hard-coded, you will always have access to the latest API features.
+iStreamPlanet's APIs implement OpenAPI 3 descriptions which are publicly linked via [RFC 8631](https://tools.ietf.org/html/rfc8631) `service-desc` link relation headers and provide auto-discovery for [CLI configuration](https://rest.sh/#/openapi?id=autoconfiguration) via the `x-cli-config` extension. This means you can use any client which understands these features to interact with our APIs.
 
 ## Installation
 
-We recommend getting started with [Restish](https://rest.sh/), a simple cURL-like commandline client for REST-ish APIs. Getting started is easy:
+We recommend getting started with [Restish](https://rest.sh/), a simple cURL-like commandline client for REST-ish APIs. Commands are generated at runtime based on our latest published OpenAPI, so you always have access to the latest API features automatically.
+
+Getting started is easy:
 
 <Tabs
-  defaultValue="mac"
+  defaultValue={function() {
+    if (ExecutionEnvironment.canUseDOM) {
+      // Try to guess the user's OS from their browser!
+      const platform = navigator.platform.toLowerCase();
+      if (platform.includes("linux")) {
+        return "linux";
+      } else if (platform.includes("win")) {
+        return "win";
+      }
+    }
+    return "mac";
+  }()}
   values={[
     { label: "macOS", value: "mac" },
     { label: "Windows", value: "win" },
@@ -25,29 +37,37 @@ We recommend getting started with [Restish](https://rest.sh/), a simple cURL-lik
 >
   <TabItem value="mac">
 
-First, make sure you have [Homebrew](https://brew.sh/) installed. After that, installing Restish is a breeze:
+First, make sure you have [Homebrew](https://brew.sh/) installed. After that, installing or upgrading Restish is a breeze:
 
 ```bash
+# Install Restish
 $ brew tap danielgtaylor/restish && brew install restish
+
+# Upgrade Restish to latest release
+$ brew upgrade restish
 ```
 
-Prefer not to use Homebrew? Then [manually download a release](https://github.com/danielgtaylor/restish/releases).
+Prefer not to use Homebrew? Then [manually download a release](https://github.com/danielgtaylor/restish/releases/latest).
 
   </TabItem>
   <TabItem value="win">
 
-Head over and [manually download a release](https://github.com/danielgtaylor/restish/releases). Unzip the executable somewhere and you are good to go!
+Head over and [manually download a release](https://github.com/danielgtaylor/restish/releases/latest). Unzip the executable somewhere and you are good to go!
 
   </TabItem>
   <TabItem value="linux">
 
-First, make sure you have [Homebrew](https://brew.sh/) installed. After that, installing Restish is a breeze:
+If you have [Homebrew](https://brew.sh/) then installing or upgrading Restish is a breeze:
 
 ```bash
+# Install Restish
 $ brew tap danielgtaylor/restish && brew install restish
+
+# Upgrade Restish to latest release
+$ brew upgrade restish
 ```
 
-Prefer not to use Homebrew? Then [manually download a release](https://github.com/danielgtaylor/restish/releases) or use `go get` if you have the Go compiler installed:
+Prefer not to use Homebrew? Then [manually download a release](https://github.com/danielgtaylor/restish/releases/latest) or use `go get` if you have the Go compiler installed:
 
 ```bash
 // Download, build & install.
@@ -63,7 +83,7 @@ Once installed you need to configure Restish to talk to the iStreamPlanet API. W
 
 ```bash
 # Configure Restish to talk to iStreamPlanet.
-$ restish api config isp https://api.istreamplanet.com
+$ restish api configure isp https://api.istreamplanet.com
 
 ? Organization ID [? for help] YOUR_VALUE_HERE
 ? Select option  [Use arrows to move, type to filter]
@@ -73,6 +93,8 @@ $ restish api config isp https://api.istreamplanet.com
 > Save and exit
 ```
 
+Restish supports multiple profiles, which can be set up via the interactive configuration prompt above or by copying & editing in `~/.restish/apis.json`. Once configured, you can use `-p` to reference the profile, for example `restish isp -p PROFILE_NAME list-channels`.
+
 ## Example Usage
 
 Commands and help are generated on the fly from the server-provided OpenAPI document. Help commands let you see what is available and how to use it.
@@ -81,8 +103,8 @@ Commands and help are generated on the fly from the server-provided OpenAPI docu
 # Get a list of all available commands.
 $ restish isp --help
 
-# See help for creating a channel.
-$ restish isp create-channel --help
+# See help for creating/updating a channel.
+$ restish isp put-channel --help
 ```
 
 ### Getting Information
@@ -97,23 +119,74 @@ $ restish isp list-sources
 $ restish isp list-channels
 ```
 
+Lists of items like sources and channels are generally paginated. By default, Restish will make as many requests as needed to get all pages of data before returning. This behavior can be disabled to get a single page, for example:
+
+```bash
+# Disable auto-pagination, and return up to 5 items from the first page.
+$ restish isp list-channels --rsh-no-paginate --page-size=5
+```
+
 Restish is smart about which URIs require authentication by matching them to pre-configured API base URIs, so you can also directly access links you find in responses. For example, you might see something like this returned when listing channels and want to get additional details:
 
 ```bash
 # Get details from a channel by link.
-$ restish https://api.istreamplanet.com/v2/channels/ch-abc123
+$ restish https://api.istreamplanet.com/v2/channels/my-channel-id
 ```
 
+#### Filtering Data
+
+Restish supports client-side [filtering & projection](https://rest.sh/#/output?id=filtering-amp-projection) of response data, making it easier to get just the information you need from the API. Filtering uses the `-f` shorthand function which accepts a JMESPath expression to run against an [object that looks like](https://rest.sh/#/output?id=response-structure):
+
+```json
+{
+  "proto": "HTTP/2.0",
+  "status": 200,
+  "headers": {
+    "Header-Name": "header value"
+  },
+  "links": {
+    "link-name": [
+      {
+        "rel": "link-name",
+        "uri": "https://link.url/..."
+      }
+    ]
+  },
+  "body": {
+    // Body is here
+  }
+}
+```
+
+Some examples:
+
+```bash
+# Get just the channel ID and name for all channels:
+$ restish isp list-channels -f 'body[].{id, name}'
+
+# Get a raw list of channel IDs that start with "test":
+$ restish isp list-channels -f 'body[?starts_with(@.id, `"test"`)]'.id -r
+
+# Get the ETag (content version) of a channel:
+$ restish isp get-channel my-channel -f `headers.Etag` -r
+
+# Get all HD encodings for a channel:
+$ restish isp get-channel my-channel -f 'body.transcode.video_encoders[?height >= `720`].{id, width, height, bit_rate}'
+```
+
+Note that enabling filtering will also enable JSON output mode.
+
 ### Writing Data
 
 Write calls take input in one of two ways: JSON passed in via stdin or a custom [CLI shorthand syntax](https://rest.sh/#/shorthand) on the commandline.
 
 ```bash
 # Pass JSON via stdin.
-$ restish isp create-channel <input.json
+$ echo '{"name": "My Test Channel", "ingest": {"source": {"id": "s-abc123"}}}' >input.json
+$ restish isp put-channel my-channel-id <input.json
 
 # Pass data on the commandline via shorthand.
-$ restish isp create-channel name: My Test Channel, source: s-abc123, ...
+$ restish isp put-channel my-channel-id name: My Test Channel, ingest.source.id: s-abc123, ...
 ```
 
 Read the [Restish documentation](https://rest.sh/) for more in-depth CLI info and check out our [Guide](/docs/guide/) and API reference for examples that show you how to use the iStreamPlanet APIs.

docs/guide/auditing.mdx

@@ -0,0 +1,72 @@
+---
+title: Auditing Channels
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+It is possible to audit all actions taken on a channel, even one that has been deleted.
+
+<Tabs
+  groupId="client"
+  defaultValue="cli"
+  values={[
+    { label: "CLI", value: "cli" },
+    { label: "Javascript", value: "js" },
+    { label: "Go", value: "go" },
+  ]}
+>
+  <TabItem value="cli">
+
+```bash
+# Get a channel timeline
+$ restish isp get-channel-timeline $CHANNEL_ID
+```
+
+  </TabItem>
+  <TabItem value="js">
+
+```js
+// TODO
+```
+
+  </TabItem>
+  <TabItem value="go">
+
+```go
+request := client.AuditOperationsApi.GetChannelTimeline(context.Background(), "CHANNEL_ID")
+entries, resp, err := request.Execute()
+
+if err.Error() != "" {
+  panic(err)
+}
+
+// Print out each action name
+for _, entry := range entries {
+  fmt.Println(entry.Action)
+}
+```
+
+  </TabItem>
+</Tabs>
+
+Individual audit entries look something like these below:
+
+```json
+{
+  "action": "put-channel",
+  "agent": "UNIQUE_USER_IDENTIFIER",
+  "request_body": "{...data as JSON string...}",
+  "status_code": 200,
+  "timestamp": "2021-01-01T12:00:00Z",
+  "trace_id": "484821178360672118"
+},
+{
+  "action": "program-start",
+  "agent": "UNIQUE_USER_IDENTIFIER",
+  "request_body": "{\"event_id\":0}",
+  "status_code": 204,
+  "timestamp": "2021-01-01T12:00:00Z",
+  "trace_id": "5179266826846428609",
+}
+```