chore(docs): update readme (#407)

README.md

@@ -50,6 +50,9 @@ val client = LithicOkHttpClient.builder()
 Alternately, set the environment with `LITHIC_API_KEY` or `LITHIC_WEBHOOK_SECRET`, and use `LithicOkHttpClient.fromEnv()` to read from the environment.
 
 ```kotlin
+import com.lithic.api.client.LithicClient
+import com.lithic.api.client.okhttp.LithicOkHttpClient
+
 val client = LithicOkHttpClient.fromEnv()
 
 // Note: you can also call fromEnv() from the client builder, for example if you need to set additional properties
@@ -70,8 +73,7 @@ Read the documentation for more configuration options.
 
 ### Example: creating a resource
 
-To create a new card, first use the `CardCreateParams` builder to specify attributes,
-then pass that to the `create` method of the `cards` service.
+To create a new card, first use the `CardCreateParams` builder to specify attributes, then pass that to the `create` method of the `cards` service.
 
 ```kotlin
 import com.lithic.api.models.Card
@@ -85,12 +87,11 @@ val card = client.cards().create(params)
 
 ### Example: listing resources
 
-The Lithic API provides a `list` method to get a paginated list of cards.
-You can retrieve the first page by:
+The Lithic API provides a `list` method to get a paginated list of cards. You can retrieve the first page by:
 
 ```kotlin
 import com.lithic.api.models.Card
-import com.lithic.api.models.Page
+import com.lithic.api.models.CardListPage
 
 val page = client.cards().list()
 for (card: Card in page.data()) {
@@ -101,15 +102,19 @@ for (card: Card in page.data()) {
 Use the `CardListParams` builder to set parameters:
 
 ```kotlin
-CardListParams params = CardListParams.builder()
+import com.lithic.api.models.CardListPage
+import com.lithic.api.models.CardListParams
+import java.time.OffsetDateTime
+
+val params = CardListParams.builder()
     .accountToken("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
     .begin(OffsetDateTime.parse("2019-12-27T18:11:19.117Z"))
     .end(OffsetDateTime.parse("2019-12-27T18:11:19.117Z"))
     .endingBefore("ending_before")
     .pageSize(1L)
     .startingAfter("starting_after")
     .state(CardListParams.State.CLOSED)
-    .build();
+    .build()
 val page1 = client.cards().list(params)
 
 // Using the `from` method of the builder you can reuse previous params values:
@@ -168,14 +173,14 @@ Card.builder().state(State.of("NEW_STATE")).build()
 
 To make a request to the Lithic API, you generally build an instance of the appropriate `Params` class.
 
-In [Example: creating a resource](#example-creating-a-resource) above, we used the `CardCreateParams.builder()` to pass to
-the `create` method of the `cards` service.
+In [Example: creating a resource](#example-creating-a-resource) above, we used the `CardCreateParams.builder()` to pass to the `create` method of the `cards` service.
 
-Sometimes, the API may support other properties that are not yet supported in the Kotlin SDK types. In that case,
-you can attach them using the `putAdditionalProperty` method.
+Sometimes, the API may support other properties that are not yet supported in the Kotlin SDK types. In that case, you can attach them using the `putAdditionalProperty` method.
 
 ```kotlin
-import com.lithic.api.models.core.JsonValue
+import com.lithic.api.core.JsonValue
+import com.lithic.api.models.CardCreateParams
+
 val params = CardCreateParams.builder()
     // ... normal properties
     .putAdditionalProperty("secret_param", JsonValue.from("4242"))
@@ -189,6 +194,8 @@ val params = CardCreateParams.builder()
 When receiving a response, the Lithic Kotlin SDK will deserialize it into instances of the typed model classes. In rare cases, the API may return a response property that doesn't match the expected Kotlin type. If you directly access the mistaken property, the SDK will throw an unchecked `LithicInvalidDataException` at runtime. If you would prefer to check in advance that that response is completely well-typed, call `.validate()` on the returned model.
 
 ```kotlin
+import com.lithic.api.models.Card
+
 val card = client.cards().create().validate()
 ```
 
@@ -203,10 +210,12 @@ card.cvv != null // false
 
 ### Response properties as JSON
 
-In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by
-this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns a `JsonField` value.
+In rare cases, you may want to access the underlying JSON value for a response property rather than using the typed version provided by this SDK. Each model property has a corresponding JSON version, with an underscore before the method name, which returns a `JsonField` value.
 
 ```kotlin
+import com.lithic.api.core.JsonField
+import java.util.Optional
+
 val field = responseObj._field
 
 if (field.isMissing()) {
@@ -228,24 +237,27 @@ if (field.isMissing()) {
 Sometimes, the server response may include additional properties that are not yet available in this library's types. You can access them using the model's `_additionalProperties` method:
 
 ```kotlin
+import com.lithic.api.core.JsonValue
+
 val secret = address._additionalProperties().get("secret_field")
 ```
 
 ---
 
 ## Pagination
 
-For methods that return a paginated list of results, this library provides convenient ways access
-the results either one page at a time, or item-by-item across all pages.
+For methods that return a paginated list of results, this library provides convenient ways access the results either one page at a time, or item-by-item across all pages.
 
 ### Auto-pagination
 
-To iterate through all results across all pages, you can use `autoPager`,
-which automatically handles fetching more pages for you:
+To iterate through all results across all pages, you can use `autoPager`, which automatically handles fetching more pages for you:
 
 ### Synchronous
 
 ```kotlin
+import com.lithic.api.models.Card
+import com.lithic.api.models.CardListPage
+
 // As a Sequence:
 client.cards().list(params).autoPager()
     .take(50)
@@ -263,12 +275,12 @@ asyncClient.cards().list(params).autoPager()
 
 ### Manual pagination
 
-If none of the above helpers meet your needs, you can also manually request pages one-by-one.
-A page of results has a `data()` method to fetch the list of objects, as well as top-level
-`response` and other methods to fetch top-level data about the page. It also has methods
-`hasNextPage`, `getNextPage`, and `getNextPageParams` methods to help with pagination.
+If none of the above helpers meet your needs, you can also manually request pages one-by-one. A page of results has a `data()` method to fetch the list of objects, as well as top-level `response` and other methods to fetch top-level data about the page. It also has methods `hasNextPage`, `getNextPage`, and `getNextPageParams` methods to help with pagination.
 
 ```kotlin
+import com.lithic.api.models.Card
+import com.lithic.api.models.CardListPage
+
 val page = client.cards().list(params)
 while (page != null) {
     for (card in page.data) {
@@ -301,31 +313,33 @@ This library throws exceptions in a single hierarchy for easy handling:
 
 - **`LithicException`** - Base exception for all exceptions
 
-  - **`LithicServiceException`** - HTTP errors with a well-formed response body we were able to parse. The exception message and the `.debuggingRequestId()` will be set by the server.
+- **`LithicServiceException`** - HTTP errors with a well-formed response body we were able to parse. The exception message and the `.debuggingRequestId()` will be set by the server.
 
-    | 400    | BadRequestException           |
-    | ------ | ----------------------------- |
-    | 401    | AuthenticationException       |
-    | 403    | PermissionDeniedException     |
-    | 404    | NotFoundException             |
-    | 422    | UnprocessableEntityException  |
-    | 429    | RateLimitException            |
-    | 5xx    | InternalServerException       |
-    | others | UnexpectedStatusCodeException |
+  | 400    | BadRequestException           |
+  | ------ | ----------------------------- |
+  | 401    | AuthenticationException       |
+  | 403    | PermissionDeniedException     |
+  | 404    | NotFoundException             |
+  | 422    | UnprocessableEntityException  |
+  | 429    | RateLimitException            |
+  | 5xx    | InternalServerException       |
+  | others | UnexpectedStatusCodeException |
 
-  - **`LithicIoException`** - I/O networking errors
-  - **`LithicInvalidDataException`** - any other exceptions on the client side, e.g.:
-    - We failed to serialize the request body
-    - We failed to parse the response body (has access to response code and body)
+- **`LithicIoException`** - I/O networking errors
+- **`LithicInvalidDataException`** - any other exceptions on the client side, e.g.:
+  - We failed to serialize the request body
+  - We failed to parse the response body (has access to response code and body)
 
 ## Network options
 
 ### Retries
 
-Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default.
-You can provide a `maxRetries` on the client builder to configure this:
+Requests that experience certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default. You can provide a `maxRetries` on the client builder to configure this:
 
 ```kotlin
+import com.lithic.api.client.LithicClient
+import com.lithic.api.client.okhttp.LithicOkHttpClient
+
 val client = LithicOkHttpClient.builder()
     .fromEnv()
     .maxRetries(4)
@@ -337,6 +351,10 @@ val client = LithicOkHttpClient.builder()
 Requests time out after 1 minute by default. You can configure this on the client builder:
 
 ```kotlin
+import com.lithic.api.client.LithicClient
+import com.lithic.api.client.okhttp.LithicOkHttpClient
+import java.time.Duration
+
 val client = LithicOkHttpClient.builder()
     .fromEnv()
     .timeout(Duration.ofSeconds(30))
@@ -348,12 +366,14 @@ val client = LithicOkHttpClient.builder()
 Requests can be routed through a proxy. You can configure this on the client builder:
 
 ```kotlin
+import com.lithic.api.client.LithicClient
+import com.lithic.api.client.okhttp.LithicOkHttpClient
+import java.net.InetSocketAddress
+import java.net.Proxy
+
 val client = LithicOkHttpClient.builder()
     .fromEnv()
-    .proxy(new Proxy(
-        Type.HTTP,
-        new InetSocketAddress("proxy.com", 8080)
-    ))
+    .proxy(Proxy(Proxy.Type.HTTP, InetSocketAddress("example.com", 8080)))
     .build()
 ```
 
@@ -362,6 +382,9 @@ val client = LithicOkHttpClient.builder()
 Requests are made to the production environment by default. You can connect to other environments, like `sandbox`, via the client builder:
 
 ```kotlin
+import com.lithic.api.client.LithicClient
+import com.lithic.api.client.okhttp.LithicOkHttpClient
+
 val client = LithicOkHttpClient.builder()
     .fromEnv()
     .sandbox()