feat: add paginator api (#30)

* feat: add paginator api

* style: make ktlint happy

src/main/kotlin/Charge.kt

@@ -11,6 +11,7 @@ import io.ktor.utils.io.*
 import java.io.File
 import java.util.function.Consumer
 import kotlinx.serialization.KSerializer
+import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.descriptors.SerialDescriptor
 import kotlinx.serialization.encoding.Decoder
@@ -123,9 +124,10 @@ public data class ChargeResponse @JvmOverloads public constructor(
 
 @Serializable
 public data class ChargeListResponse(
-  public val charges: List<Charge>,
-  public val pageInfo: PageInfo,
-)
+  @SerialName("charges")
+  public override var items: List<Charge>,
+  public override var pageInfo: PageInfo,
+) : PageInstance<Charge>
 
 @Serializable
 public data class ChargeDeleteResponse(

src/main/kotlin/Customer.kt

@@ -4,6 +4,7 @@ package br.com.openpix.sdk
 
 import io.ktor.client.call.*
 import io.ktor.client.request.*
+import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 @Serializable
@@ -35,9 +36,10 @@ public data class CustomerResponse(
 
 @Serializable
 public data class CustomerListResponse(
-  public val customers: List<Customer>,
-  public val pageInfo: PageInfo,
-)
+  @SerialName("customers")
+  public override var items: List<Customer>,
+  public override var pageInfo: PageInfo,
+) : PageInstance<Customer>
 
 @Serializable
 public data class CustomerRequest @JvmOverloads public constructor(

src/main/kotlin/Paginator.kt

@@ -0,0 +1,129 @@
+package br.com.openpix.sdk
+
+import io.ktor.client.call.*
+import io.ktor.client.request.*
+import java.util.concurrent.Future
+import kotlinx.coroutines.future.future
+
+/**
+ * Paginator for the API. Used to paginate through the API. It's used by the SDK to paginate through the API.
+ *
+ * @property sdk The SDK instance. Used to make requests.
+ */
+public class Paginator<T> @PublishedApi internal constructor(
+  /**
+   * The SDK instance. Used to make requests.
+   */
+  private val sdk: WooviSDK,
+  private var skipping: Int,
+  private val pageSize: Int,
+  private val initialQueries: Map<String, String>,
+  private val request: suspend WooviSDK.(queries: Map<String, String>) -> PageInstance<T>,
+) {
+  private var page: PageInstance<T>? = null
+
+  /**
+   * The current page of the paginator. Starts at 1.
+   *
+   * @return The current page of the paginator.
+   */
+  public suspend fun items(): List<T> {
+    if (page == null) {
+      page = request(sdk, initialQueries + mapOf("skip" to skipping.toString()))
+    }
+
+    return page!!.items
+  }
+
+  /**
+   * The current page of the paginator. Starts at 1.
+   *
+   * @return The current page of the paginator.
+   */
+  public fun itemsAsync(): Future<List<T>> = sdk.future {
+    items()
+  }
+
+  /**
+   * Advances to the next page.
+   */
+  public fun next() {
+    this.skipping += pageSize
+    this.page = null // Invalidates the current page cache
+  }
+
+  /**
+   * Goes back to the previous page.
+   */
+  public fun previous() {
+    this.skipping -= pageSize
+    this.page = null // Invalidates the current page cache
+  }
+
+  /**
+   * The current page information.
+   */
+  public suspend fun pageInfo(): PageInfo {
+    if (page == null) {
+      page = request(sdk, initialQueries + mapOf("skip" to skipping.toString()))
+    }
+
+    return page!!.pageInfo
+  }
+
+  /**
+   * The current page information.
+   */
+  public fun pageInfoAsync(): Future<PageInfo> = sdk.future {
+    pageInfo()
+  }
+
+  public companion object {
+    /**
+     * Creates a paginator for the API. Used to paginate through the API.
+     *
+     * It's used by the SDK to paginate through the API.
+     */
+    public inline fun <reified R : PageInstance<T>, T> createPaginator(
+      sdk: WooviSDK,
+      endpoint: String,
+      pageSize: Int,
+      initialQueries: Map<String, String?>,
+    ): Paginator<T> {
+      val queriesNotNullable = initialQueries.filterValues { it != null }.mapValues { it.value!! }
+
+      return Paginator(sdk, 0, pageSize, queriesNotNullable) { queries ->
+        sdk.client
+          .get(endpoint) {
+            queries.forEach { (key, value) ->
+              parameter(key, value)
+            }
+          }
+          .body<R>()
+      }
+    }
+  }
+}
+
+public class PaginationQueries : HashMap<String, String>() {
+  public var start: String?
+    get(): String? = this["start"]
+    set(value) {
+      if (value != null) {
+        this["start"] = value
+      }
+    }
+
+  public var end: String?
+    get(): String? = this["end"]
+    set(value) {
+      if (value != null) {
+        this["end"] = value
+      }
+    }
+}
+
+public interface PageInstance<T> {
+  public var items: List<T>
+  public var pageInfo: PageInfo
+}

src/main/kotlin/Payment.kt

@@ -5,14 +5,16 @@ package br.com.openpix.sdk
 import io.ktor.client.call.*
 import io.ktor.client.request.*
 import kotlin.text.get
+import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 @Serializable
 public data class PaymentListResponse(
   public val status: String? = null,
-  public val payments: List<PaymentResponseObject>,
-  public val pageInfo: PageInfo,
-)
+  @SerialName("payments")
+  public override var items: List<PaymentResponseObject>,
+  public override var pageInfo: PageInfo,
+) : PageInstance<PaymentResponseObject>
 
 @Serializable
 public data class PaymentResponseObject(

src/main/kotlin/PixQrCode.kt

@@ -4,6 +4,7 @@ package br.com.openpix.sdk
 
 import io.ktor.client.call.*
 import io.ktor.client.request.*
+import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 @Serializable
@@ -24,8 +25,10 @@ public data class PixQrCodeResponse(
 
 @Serializable
 public data class PixQrCodeList(
-  public val pixQrCodes: List<PixQrCode> = emptyList(),
-)
+  @SerialName("pixQrCodes")
+  public override var items: List<PixQrCode> = emptyList(),
+  public override var pageInfo: PageInfo,
+) : PageInstance<PixQrCode>
 
 @Serializable
 public data class PixQrCode(

src/main/kotlin/Refund.kt

@@ -4,6 +4,7 @@ package br.com.openpix.sdk
 
 import io.ktor.client.call.*
 import io.ktor.client.request.*
+import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 @Serializable
@@ -29,9 +30,10 @@ public data class RefundResponse(public val refund: Refund)
 
 @Serializable
 public data class RefundListResponse(
-  public val refunds: List<Refund>,
-  public val pageInfo: PageInfo,
-)
+  @SerialName("refunds")
+  public override var items: List<Refund>,
+  public override var pageInfo: PageInfo,
+) : PageInstance<Refund>
 
 @Serializable
 public data class RefundRequestBody(

src/main/kotlin/Transaction.kt

@@ -44,9 +44,10 @@ public enum class TransactionKind {
 @Serializable
 public data class TransactionListResponse(
   public val status: String,
-  public val transactions: List<Transaction>,
-  public val pageInfo: PageInfo,
-)
+  @SerialName("transactions")
+  public override var items: List<Transaction>,
+  public override var pageInfo: PageInfo,
+) : PageInstance<Transaction>
 
 @Serializable
 public data class TransactionResponse(public val transaction: Transaction)

src/main/kotlin/Webhook.kt

@@ -51,9 +51,10 @@ public data class WebhookResponse(public val webhook: Webhook)
 
 @Serializable
 public data class WebhookListResponse(
-  public val webhooks: List<Webhook>,
-  public val pageInfo: PageInfo,
-)
+  @SerialName("webhooks")
+  public override var items: List<Webhook>,
+  public override var pageInfo: PageInfo,
+) : PageInstance<Webhook>
 
 @Serializable
 public enum class WebhookEvent {