wip: docs improvements

Sources/Buildkite/Buildkite.docc/Articles/Authorization.md

@@ -1,9 +1,11 @@
 # Authorization
 
-Buildkite supports resources across several different APIs with a variety of versions and authorization interfaces. ``BuildkiteClient`` has built-in support to interoperate between the different APIs from a single client. 
+Authorizing with Buildkite APIs.
 
 ## Overview
 
+Buildkite supports resources across several different APIs with a variety of versions and authorization interfaces. ``BuildkiteClient`` has built-in support to interoperate between the different APIs from a single client. 
+
 The most basic means of authorizing with a single service in Buildkite is by the declaration of a fixed token string. The client instance will store a copy of this string in memory and use it with all subsequent requests.
 
 ```swift

Sources/Buildkite/Buildkite.docc/Articles/GettingStarted.md

@@ -1,14 +1,14 @@
-# Getting Started with Buildkite
+# Getting Started
 
 Initialize a client and get started with sending resources by listing all pipelines. 
 
 ## Overview
 
-// TODO
+This article is an overview of how to set up your Buildkite client to interact with the REST API.
 
 ### Get Your Access Token
 
-In order to access the Buildkite API you must first create an API access token. Follow Buildkite's [own documentation on managing tokens](https://buildkite.com/docs/apis/managing-api-tokens) for more information on what to do. Keep in mind that securely storing tokens used with this package is the responsibility of the developer. 
+In order to access the Buildkite API you must first create an API access token. Follow Buildkite's own documentation on [managing API tokens](https://buildkite.com/docs/apis/managing-api-tokens) for more information on what to do. Keep in mind that securely storing tokens used with this package is the responsibility of the developer. 
 
 ### Create a Buildkite Client
 

Sources/Buildkite/Buildkite.docc/Articles/Webhooks.md

@@ -0,0 +1,9 @@
+# Webhooks
+
+Responding to webhook events from Buildkite.
+
+## Overview
+
+The [Buildkite Webhook API](https://buildkite.com/docs/apis/webhooks) is used to consume lifecycle events from Buildkite in real-time from your server application.
+
+> Note: This will not be a tutorial to implement a server application, nor one to respond to Buildkite webhook events specifically. The purpose of this article is to inform how to use the helpers this client library provides to make implementing your webhooks easier. This article assumes you know how how to configure a new route in your server and expose it in such a way where Buildkite can communicate with it. 

Sources/Buildkite/Buildkite.docc/Buildkite.md

@@ -13,59 +13,59 @@ The entire publicly documented REST API surface is supported by this package.
 - <doc:GettingStarted>
 - ``BuildkiteClient``
 
-### Resources
-
-- ``AccessToken/Resources``
-- ``Agent/Resources``
-- ``AgentMetrics/Resources``
-- ``Annotation/Resources``
-- ``Artifact/Resources``
-- ``Build/Resources``
-- ``Emoji/Resources``
-- ``Job/Resources``
-- ``Meta/Resources``
-- ``Organization/Resources``
-- ``Pipeline/Resources``
-- ``Team/Resources``
-- ``TestAnalytics/Resources``
-- ``User/Resources``
-- ``Followable``
-- ``Resource``
-
-### GraphQL
-
-- <doc:UsingGraphQL>
-- ``GraphQL``
-- ``JSONValue``
-
-### Pagination
-
-- ``Page``
-- ``PageOptions``
-- ``PaginatedResource``
-
-### Models
+### REST API
 
 - ``AccessToken``
 - ``Agent``
 - ``Annotation``
 - ``Artifact``
 - ``Build``
 - ``Emoji``
+- ``Followable``
 - ``Job``
 - ``Meta``
 - ``Organization``
 - ``Pipeline``
 - ``Team``
 - ``User``
 
-### Advanced
+### Authorization
 
 - <doc:Authorization>
+- ``TokenProvider``
+
+#### Pagination
+
+- ``Page``
+- ``PageOptions``
+- ``PaginatedResource``
+
+### GraphQL API
+
+- <doc:UsingGraphQL>
+- ``GraphQL``
+- ``JSONValue``
+
+### Agent API
+
+- ``AgentMetrics``
+
+### Test Analytics API
+
+- ``TestAnalytics``
+- ``Trace``
+
+### Webhook API
+
+- <doc:Webhooks>
+- ``WebhookEvent``
+
+### Advanced
+
 - ``Configuration``
 - ``APIVersion``
+- ``Resource``
 - ``Transport``
-- ``TokenProvider``
 - ``Response``
 - ``StatusCode``
 - ``BuildkiteError``

Sources/Buildkite/Models/WebhookEvent.swift

@@ -13,10 +13,10 @@ import FoundationNetworking
 #endif
 
 public enum WebhookEvent: Codable, Equatable {
-    case ping(WebhookEvents.Ping)
-    case build(WebhookEvents.Build)
-    case job(WebhookEvents.Job)
-    case agent(WebhookEvents.Agent)
+    case ping(Ping)
+    case build(Build)
+    case job(Job)
+    case agent(Agent)
 
     private enum Unassociated: String, Codable {
         case ping
@@ -41,13 +41,13 @@ public enum WebhookEvent: Codable, Equatable {
         let event = try container.decode(Unassociated.self, forKey: .event)
         switch event {
         case .ping:
-            self = .ping(try WebhookEvents.Ping(from: decoder))
+            self = .ping(try Ping(from: decoder))
         case .buildScheduled, .buildRunning, .buildFinished:
-            self = .build(try WebhookEvents.Build(from: decoder))
+            self = .build(try Build(from: decoder))
         case .jobScheduled, .jobStarted, .jobFinished, .jobActivated:
-            self = .job(try WebhookEvents.Job(from: decoder))
+            self = .job(try Job(from: decoder))
         case .agentConnected, .agentLost, .agentDisconnected, .agentStopping, .agentStopped:
-            self = .agent(try WebhookEvents.Agent(from: decoder))
+            self = .agent(try Agent(from: decoder))
         }
     }
 
@@ -67,9 +67,22 @@ public enum WebhookEvent: Codable, Equatable {
     private enum CodingKeys: String, CodingKey {
         case event
     }
-}
 
-public enum WebhookEvents {
+    public struct Service: Codable, Equatable, Identifiable {
+        public var id: UUID
+        public var provider: String
+        public var settings: Settings
+
+        public struct Settings: Codable, Equatable {
+            public var url: URL
+        }
+    }
+
+    public struct Sender: Codable, Equatable, Identifiable {
+        public var id: UUID
+        public var name: String
+    }
+
     public struct Ping: Codable, Equatable {
         /// The notification service that sent this webhook
         public var service: Service
@@ -142,58 +155,3 @@ public enum WebhookEvents {
         }
     }
 }
-
-public struct Service: Codable, Equatable, Identifiable {
-    public var id: UUID
-    public var provider: String
-    public var settings: Settings
-
-    public struct Settings: Codable, Equatable {
-        public var url: URL
-    }
-}
-
-public struct Sender: Codable, Equatable, Identifiable {
-    public var id: UUID
-    public var name: String
-}
-
-
-// Received POST {
-//   host: '3424-2601-192-8600-bfc0-a963-fc8-ece3-46b8.ngrok.io',
-//   'user-agent': 'Buildkite-Request',
-//   'content-length': '772',
-//   accept: '*/*',
-//   'accept-encoding': 'gzip;q=1.0,deflate;q=0.6,identity;q=0.3',
-//   'content-type': 'application/json',
-//   'x-buildkite-event': 'ping',
-//   'x-buildkite-request': '01813932-4ac5-490a-82cd-eb6bcb2b55b6',
-//   'x-buildkite-token': '62d32cdc0687926d9c556dff46a6f0e8',
-//   'x-datadog-parent-id': '3879493372906842722',
-//   'x-datadog-sampling-priority': '0',
-//   'x-datadog-trace-id': '2090185261397568562',
-//   'x-forwarded-for': '100.24.182.113',
-//   'x-forwarded-proto': 'https'
-// } {
-//   event: 'ping',
-//   service: {
-//     id: '69774b46-b443-4ed9-8ee5-7817f9d5d3d6',
-//     provider: 'webhook',
-//     settings: {
-//       url: 'https://3424-2601-192-8600-bfc0-a963-fc8-ece3-46b8.ngrok.io'
-//     }
-//   },
-//   organization: {
-//     id: '19ab06b9-17cd-4937-a44b-834976e5f894',
-//     graphql_id: 'T3JnYW5pemF0aW9uLS0tMTlhYjA2YjktMTdjZC00OTM3LWE0NGItODM0OTc2ZTVmODk0',
-//     url: 'https://api.buildkite.com/v2/organizations/asky',
-//     web_url: 'https://buildkite.com/asky',
-//     name: 'asky',
-//     slug: 'asky',
-//     agents_url: 'https://api.buildkite.com/v2/organizations/asky/agents',
-//     emojis_url: 'https://api.buildkite.com/v2/organizations/asky/emojis',
-//     created_at: '2020-03-14T20:04:43.567Z',
-//     pipelines_url: 'https://api.buildkite.com/v2/organizations/asky/pipelines'
-//   },
-//   sender: { id: 'df71cc10-3cf0-49b0-9acb-5882342ca649', name: 'Aaron Sky' }
-// }