Update README and javadoc

Improve docs

- Use Dokka HTML format which is better for Kotlin
- Move Model classes to new package so docs are better
  organized
- Hide internal package from generated docs, along with
  OpenApi infrastructure packages

Author: gabrielfeo

.openapi-generator-ignore

@@ -4,7 +4,7 @@ build/generated/openapi-generator/api/*
 build/generated/openapi-generator/gradle/**/*
 build/generated/openapi-generator/docs/*
 build/generated/openapi-generator/src/main/AndroidManifest.xml
-build/generated/openapi-generator/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/ApiClient.kt
+build/generated/openapi-generator/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/internal/infrastructure/ApiClient.kt
 build/generated/openapi-generator/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/BuildsApi.kt
 build/generated/openapi-generator/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/BuildCacheApi.kt
 build/generated/openapi-generator/src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/MetaApi.kt

README.md

@@ -12,96 +12,167 @@ builds.forEach {
 
 ## Setup
 
-Add a dependency by copying these lines to the top of your `kts` scripts:
+Set up your environment once and use the library from any script in your machine.
+
+- `GRADLE_ENTERPRISE_URL` environment variable: the URL of your Gradle Enterprise instance
+- `GRADLE_ENTERPRISE_API_TOKEN` environment variable: an API access token for the Gradle
+  Enterprise instance. Alternatively, can be a macOS keychain entry labeled
+  `gradle-enterprise-api-token` (recommended).
+
+That's it! From any `kts` script, you can add a dependency on the library and start querying the
+API:
 
 ```kotlin
 @file:Repository("https://jitpack.io")
 @file:DependsOn("com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0")
+
+val builds = api.getBuilds(since = 0, maxBuilds = 10).execute().body()!!
+builds.forEach {
+  println(it)
+}
 ```
 
-Following convention over configuration, set:
-- the URL of your Gradle Enterprise instance, in environment variable `GRADLE_ENTERPRISE_URL`
-- an API access token, either in macOS keychain labeled as "gradle-enterprise-api-token"
-  or in an environment variable named `GRADLE_ENTERPRISE_API_TOKEN`
+See the [sample script](./sample.main.kts) for a complete example.
+
+<details>
+  <summary>Optional setup</summary>
+
+  All of the following have default values and are completely optional. See
+  [Api.kt](src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/Api.kt) for details.
+
+  ##### Caching
+
+  Gradle Enterprise API disallows HTTP caching, but this library forces
+  caching for faster queries. Caching is split in two categories:
+
+  1. Short-term cache (default max-age of 1 day)
+    - `/api/builds`
+  2. Long-term cache (default max-age of 1 year)
+    - `/api/builds/{id}/gradle-attributes`
+    - `/api/builds/{id}/maven-attributes`
 
-By doing so, any script can query `api` without additional setup. See the [sample
-script](./sample.main.kts) for a complete example.
+  max-age and cached URLs can be changed with options below.
+
+  - `GRADLE_ENTERPRISE_API_CACHE_DIR`: HTTP cache location. Defaults to the system temporary
+    directory.
+  - `GRADLE_ENTERPRISE_API_MAX_CACHE_SIZE`: Max size of the HTTP cache in bytes. Defaults to ~1GB.
+  - `GRADLE_ENTERPRISE_API_SHORT_TERM_CACHE_URL_PATTERN`: Regex pattern to match API URLs that are
+    OK to store short-term in the HTTP cache.
+  - `GRADLE_ENTERPRISE_API_SHORT_TERM_CACHE_MAX_AGE`: Max age in seconds of each response stored
+    short-term in the HTTP cache.
+  - `GRADLE_ENTERPRISE_API_LONG_TERM_CACHE_URL_PATTERN`: Regex pattern to match API URLs that are
+    OK to store long-term in the HTTP cache.
+  - `GRADLE_ENTERPRISE_API_LONG_TERM_CACHE_MAX_AGE`: Max age in seconds of each response stored
+    long-term in the HTTP cache.
+
+  ##### Concurrency
+
+  - `GRADLE_ENTERPRISE_API_MAX_CONCURRENT_REQUESTS`: Maximum amount of concurrent requests
+    allowed. Defaults to 15.
+
+  ##### Debugging
+
+  - `GRADLE_ENTERPRISE_API_DEBUG_LOGGING`: `true` to enable debug logging from the library. Defaults
+    to `false`.
+
+</details>
+
+<details>
+  <summary>Setup in full projects (non-scripts)</summary>
+
+  You can also use it in a full Kotlin project instead of a script. Just add a dependency:
+
+  ```kotlin
+  repositories {
+    maven(url = "https://jitpack.io")
+  }
+  dependencies {
+    implementation("com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0")
+  }
+  ```
+
+  <details>
+    <summary>Groovy</summary>
+
+    ```groovy
+    repositories {
+      maven { url = 'https://jitpack.io' }
+    }
+    dependencies {
+      implementation 'com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0'
+    }
+    ```
+
+  </details>
+
+  Any option can also be changed from code rather than from environment, as long as it's done
+  before the first `api` usage.
+
+  ```kotlin
+  baseUrl = { "https://my.ge.org" }
+  accessToken = { getFromVault("ge-api-token") }
+  api.getBuilds(id = "hy5nxbzfjxe5k")
+  ```
+
+</details>
 
 ## Usage
 
-The library provides API endpoints as a single [Retrofit][2] Service interface:
-`GradleEnterpriseApi`. It's ready-to-use as the global `api` instance:
+API endpoints are provided as a single interface: `GradleEnterpriseApi`. It's
+initialized and ready-to-use as the global `api` instance:
 
 ```kotlin
 api.getBuild(id = "hy5nxbzfjxe5k")
 ```
 
 It's recommended to learn about endpoints and their responses through IDE auto-complete. Javadoc
-appearing in auto-complete is the full API manual. Each method is documented with
-params and possible status codes.
+appearing in auto-complete is the full API manual, same as Gradle's online docs.
+
+This library provides a few extension functions on top of the regular API:
+
+```kotlin
+// Regular query to /api/builds, limited to 1000 builds server-side
+api.getBuilds(since = lastMonth)
+// Streams all available builds from a given date, split in as getBuilds
+// as needed
+api.getBuildsFlow(since = lastMonth)
+```
+
+```kotlin
+// To get build scan data such as username, tags and custom values, one
+// must usually query /api/builds/{id}/gradle-attributes per-build, which
+// is verbose and slow (1 request at a time)
+api.getBuildsFlow(since = lastMonth)
+  .map { build -> api.getGradleAttributes(id = build.id) }
+// Streams all available builds as GradleAttributes from a given date,
+// requesting more than 1 build at a time.
+api.getGradleAttributesFlow(since = lastMonth)
+```
 
-Helper functions are also available:
-- `GradleEnterpriseApi.buildsSequence()` returns a sequence making paged requests underneath
 
 ## More info
 
 - Currently built for Gradle Enterprise `2022.4`, but can be used with previous versions.
 - Use JDK 8 or 14+ to run, if you want to avoid the ["illegal reflective access" warning about
   Retrofit][3]
-- There is a global instance `okHttpClient` so you can change what's needed, but also concurrency 
+- There is a global instance `okHttpClient` so you can change what's needed, but also concurrency
   shortcuts `maxConcurrentRequests` and `shutdown()`.
   - `maxConcurrentRequests` is useful to speed up scripts, but if you start getting HTTP 504 from
-    your GE instance, decreasing this value should help. 
+    your GE instance, decreasing this value should help.
   - The script will keep running for an extra ~60s after code finishes, as an [expected behavior
-  of OkHttp][4], unless you call `shutdown()` (global function). 
-- All classes are in the same package, so that if you need to make small edits to scripts where
-  there's no auto-complete, a single wildcard import can be used:
+  of OkHttp][4], unless you call `shutdown()` (global function).
+- All classes live in these two packages. If you need to make small edits to scripts where 
+  there's no auto-complete, wildcard imports can be used:
 
 ```kotlin
 import com.gabrielfeo.gradle.enterprise.api.*
+import com.gabrielfeo.gradle.enterprise.api.model.*
 ```
 
 ###  Internals
 
 API classes such as `GradleEnterpriseApi` and response models are generated from the offical
-[API spec][5], using the [OpenAPI Generator Gradle Plugin][6]. Actual project classes are a thin
-layer over the generated code, to make it easy to use from scripts.
-
-### Custom setups
-
-You can also use it in a full Kotlin project instead of a script. Just add a dependency:
-
-```kotlin
-repositories {
-  maven(url = "https://jitpack.io")
-}
-dependencies {
-  implementation("com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0")
-}
-```
-
-<details>
-<summary>Groovy</summary>
-
-```groovy
-repositories {
-  maven { url = 'https://jitpack.io' }
-}
-dependencies {
-  implementation 'com.github.gabrielfeo:gradle-enterprise-api-kotlin:1.0'
-}
-```
-
-</details>
-
-`api` is ready-to-use if conventions are followed, but if you'd rather you can set `baseUrl` and
-`accessToken` from code instead, before using `api`:
-
-```kotlin
-baseUrl = "https://my.ge.org"
-accessToken = "abcdefg"
-api.getBuild(id = "hy5nxbzfjxe5k")
-```
+[API spec][5], using the [OpenAPI Generator Gradle Plugin][6].
 
 [1]: https://docs.gradle.com/enterprise/api-manual/
 [2]: https://square.github.io/retrofit/

build.gradle.kts

@@ -1,3 +1,6 @@
+import org.jetbrains.dokka.DokkaConfiguration.Visibility.PUBLIC
+import org.jetbrains.dokka.gradle.DokkaTask
+
 plugins {
     val kotlinVersion = "1.7.10"
     id("org.jetbrains.kotlin.jvm") version kotlinVersion
@@ -8,7 +11,7 @@ plugins {
 }
 
 group = "com.github.gabrielfeo"
-version = "1.0"
+version = "0.7"
 
 val downloadApiSpec by tasks.registering {
     val geVersion = providers.gradleProperty("gradle.enterprise.version").get()
@@ -30,9 +33,9 @@ openApiGenerate {
     val ignoreFile = project.layout.projectDirectory.file(".openapi-generator-ignore")
     ignoreFileOverride.set(ignoreFile.asFile.absolutePath)
     apiPackage.set("com.gabrielfeo.gradle.enterprise.api")
-    modelPackage.set("com.gabrielfeo.gradle.enterprise.api")
-    packageName.set("com.gabrielfeo.gradle.enterprise.api")
-    invokerPackage.set("com.gabrielfeo.gradle.enterprise.api")
+    modelPackage.set("com.gabrielfeo.gradle.enterprise.api.model")
+    packageName.set("com.gabrielfeo.gradle.enterprise.api.internal")
+    invokerPackage.set("com.gabrielfeo.gradle.enterprise.api.internal")
     additionalProperties.put("library", "jvm-retrofit2")
 }
 
@@ -52,8 +55,25 @@ java {
     }
 }
 
+tasks.withType<DokkaTask>().configureEach {
+    dokkaSourceSets.all {
+        jdkVersion.set(8)
+        suppressGeneratedFiles.set(false)
+        documentedVisibilities.set(setOf(PUBLIC))
+        perPackageOption {
+            matchingRegex.set(""".*\.internal.*""")
+            suppress.set(true)
+        }
+        externalDocumentationLink("https://kotlinlang.org/api/kotlinx.coroutines/")
+        externalDocumentationLink("https://square.github.io/okhttp/4.x/okhttp/")
+        externalDocumentationLink("https://square.github.io/retrofit/2.x/retrofit/")
+        externalDocumentationLink("https://square.github.io/moshi/1.x/moshi/")
+        externalDocumentationLink("https://square.github.io/moshi/1.x/moshi-kotlin/")
+    }
+}
+
 tasks.named<Jar>("javadocJar") {
-    from(tasks.dokkaJavadoc)
+    from(tasks.dokkaHtml)
 }
 
 publishing {

src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/Api.kt

@@ -113,7 +113,7 @@ var cacheDir = System.getenv("GRADLE_ENTERPRISE_API_CACHE_DIR")?.let(::File)
     ?: File(System.getProperty("java.io.tmpdir"), "gradle-enterprise-api-kotlin-cache")
 
 /**
- * Enables debug logging from the library. All logging is output to the program's standard streams.
- * By default, uses environment variable `GRADLE_ENTERPRISE_API_DEBUG_LOGGING` or `false`.
+ * Enables debug logging from the library. All logging is output to stderr. By default, uses
+ * environment variable `GRADLE_ENTERPRISE_API_DEBUG_LOGGING` or `false`.
  */
 var debugLoggingEnabled = System.getenv("GRADLE_ENTERPRISE_API_DEBUG_LOGGING").toBoolean()

src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/GradleEnterpriseApiExtensions.kt

@@ -1,10 +1,10 @@
 package com.gabrielfeo.gradle.enterprise.api
 
+import com.gabrielfeo.gradle.enterprise.api.model.*
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.GlobalScope
 import kotlinx.coroutines.async
 import kotlinx.coroutines.flow.*
-import retrofit2.HttpException
 import retrofit2.await
 
 private const val API_MAX_BUILDS = 1000

src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/ModelExtensions.kt

@@ -1,5 +1,7 @@
 package com.gabrielfeo.gradle.enterprise.api
 
+import com.gabrielfeo.gradle.enterprise.api.model.*
+
 operator fun List<BuildAttributesValue>.get(name: String): String? {
     return find { it.name == name }?.value
 }

src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/internal/OkHttpClient.kt

@@ -1,6 +1,6 @@
 package com.gabrielfeo.gradle.enterprise.api.internal
 
-import com.gabrielfeo.gradle.enterprise.api.auth.HttpBearerAuth
+import com.gabrielfeo.gradle.enterprise.api.internal.auth.HttpBearerAuth
 import com.gabrielfeo.gradle.enterprise.api.internal.caching.CacheEnforcingInterceptor
 import com.gabrielfeo.gradle.enterprise.api.internal.caching.CacheHitLoggingInterceptor
 import com.gabrielfeo.gradle.enterprise.api.internal.caching.cache
@@ -12,7 +12,7 @@ import com.gabrielfeo.gradle.enterprise.api.shortTermCacheMaxAge
 import com.gabrielfeo.gradle.enterprise.api.shortTermCacheUrlPattern
 import okhttp3.OkHttpClient
 
-val okHttpClient: OkHttpClient by lazy {
+internal val okHttpClient: OkHttpClient by lazy {
     OkHttpClient.Builder()
         .cache(cache)
         .addInterceptor(HttpBearerAuth("bearer", accessToken()))

src/main/kotlin/com/gabrielfeo/gradle/enterprise/api/internal/Retrofit.kt

@@ -1,12 +1,12 @@
 package com.gabrielfeo.gradle.enterprise.api.internal
 
 import com.gabrielfeo.gradle.enterprise.api.baseUrl
-import com.gabrielfeo.gradle.enterprise.api.infrastructure.Serializer
+import com.gabrielfeo.gradle.enterprise.api.internal.infrastructure.Serializer
 import retrofit2.Retrofit
 import retrofit2.converter.moshi.MoshiConverterFactory
 import retrofit2.converter.scalars.ScalarsConverterFactory
 
-val retrofit: Retrofit by lazy {
+internal val retrofit: Retrofit by lazy {
     Retrofit.Builder()
         .baseUrl(baseUrl())
         .addConverterFactory(ScalarsConverterFactory.create())