Skip to content

Commit d8fd422

Browse files
mrapplexzmrapplexz
committed
Document the rest of the lib
1 parent 849ea3e commit d8fd422

File tree

10 files changed

+149
-119
lines changed

10 files changed

+149
-119
lines changed

‎src/commonMain/kotlin/net/pearx/kpastebin/PastebinAccount.kt

Lines changed: 0 additions & 40 deletions
This file was deleted.

‎src/commonMain/kotlin/net/pearx/kpastebin/PastebinClient.kt

Lines changed: 88 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,148 @@
11
package net.pearx.kpastebin
22

3-
import io.ktor.client.HttpClient
4-
import io.ktor.client.features.defaultRequest
53
import io.ktor.client.request.post
64
import io.ktor.http.*
75
import net.pearx.kpastebin.internal.*
8-
import net.pearx.kpastebin.internal.checkPastebinResponse
96
import net.pearx.kpastebin.model.ExpireDate
107
import net.pearx.kpastebin.model.PasteDetails
118
import net.pearx.kpastebin.model.Privacy
129
import net.pearx.kpastebin.model.UserDetails
1310

14-
public class PastebinClient(private val devKey: String) {
15-
private suspend fun sendRequest(url: String, parameters: Parameters): String {
11+
/**
12+
* Pastebin API client with specified unique developer API key [devKey].
13+
* You can get your key on [official Pastebin website](https://pastebin.com/doc_api#1).
14+
*
15+
* @param userKey user key used for requests. Use null for guest user.
16+
*/
17+
public class PastebinClient(
18+
private val devKey: String,
19+
/**
20+
* User key used for requests. Use null for guest user. It also can be set using [login] method.
21+
*/
22+
public var userKey: String? = null
23+
) {
24+
private suspend fun sendRequest(url: String, userKeyRequired: Boolean, parameters: Parameters): String {
25+
val userKey = userKey
26+
if (userKeyRequired && userKey == null)
27+
throw InvalidUserKeyException("The 'userKey' property is null. It can be initialized by setting it directly or using the 'login' function.")
1628
val out = Http.post<String> {
1729
contentType(ContentType.Application.FormUrlEncoded)
1830
this.url.takeFrom(url)
1931
body = Parameters.build {
2032
append("api_dev_key", devKey)
33+
if (userKey != null)
34+
append("api_user_key", userKey)
2135
appendAll(parameters)
2236
}.formUrlEncode()
2337
}
2438
checkPastebinResponse(out)
2539
return out
2640
}
2741

28-
private suspend inline fun sendRequest(url: String, parametersBuilder: ParametersBuilder.() -> Unit) = sendRequest(url, Parameters.build(parametersBuilder))
42+
private suspend inline fun sendRequest(url: String, userKeyRequired: Boolean, parametersBuilder: ParametersBuilder.() -> Unit) = sendRequest(url, userKeyRequired, Parameters.build(parametersBuilder))
2943

44+
/**
45+
* Publishes a new paste with specified [text].
46+
* If [userKey] is null, the paste will be published anonymously.
47+
*
48+
* @param name paste title.
49+
* @param format paste syntax highlighting format. Please see [Pastebin documentation](https://pastebin.com/doc_api#5) for the list of available options.
50+
* @param privacy paste privacy status.
51+
* @param expireDate paste expiration duration.
52+
*
53+
* @throws InvalidUserKeyException when [userKey] is invalid or expired.
54+
* @throws PastePerDayLimitException when paste limit for this IP per day is exceeded.
55+
* @throws FreePasteLimitException when paste limit for current user is exceeded.
56+
* @throws PasteSizeException when [text] exceeds the size limit.
57+
* @throws InvalidPasteFormatException when specified [format] is invalid.
58+
*/
3059
public suspend fun createPaste(
3160
text: String,
32-
userKey: String? = null,
33-
name: String? = null,
34-
format: String? = null,
35-
privacy: Privacy? = null,
36-
expireDate: ExpireDate? = null
61+
name: String = "",
62+
format: String = "text",
63+
privacy: Privacy = Privacy.PUBLIC,
64+
expireDate: ExpireDate = ExpireDate.NEVER
3765
): String {
38-
return sendRequest(API_URL_POST) {
66+
return sendRequest(API_URL_POST, false) {
3967
append("api_option", "paste")
4068
append("api_paste_code", text)
41-
if (userKey != null)
42-
append("api_user_key", userKey)
43-
if (name != null)
44-
append("api_paste_name", name)
45-
if (format != null)
46-
append("api_paste_format", format)
47-
if (privacy != null)
48-
append("api_privacy", privacy.ordinal.toString())
49-
if (expireDate != null)
50-
append("api_paste_expire_date", expireDate.code)
69+
append("api_paste_name", name)
70+
append("api_paste_format", format)
71+
append("api_privacy", privacy.ordinal.toString())
72+
append("api_paste_expire_date", expireDate.code)
5173
}
5274
}
5375

54-
public suspend fun login(username: String, password: String): String {
55-
return sendRequest(API_URL_LOGIN) {
76+
/**
77+
* Log ins into Pastebin account using provided [username] and [password] combination and sets the [userKey] property.
78+
*
79+
* @throws InvalidLoginException when specified [username]/[password] combination is invalid.
80+
* @throws AccountNotActiveException when the account is not active.
81+
*/
82+
public suspend fun login(username: String, password: String) {
83+
userKey = sendRequest(API_URL_LOGIN, false) {
5684
append("api_user_name", username)
5785
append("api_user_password", password)
5886
}
5987
}
6088

61-
public suspend fun listPastes(userKey: String, resultsLimit: Int? = null): List<PasteDetails> {
62-
val out = sendRequest(API_URL_POST) {
63-
append("api_user_key", userKey)
89+
/**
90+
* Lists pastes created by this user.
91+
*
92+
* @param resultsLimit maximum number of results returned. It should be in range of 1 to 1000.
93+
*
94+
* @throws InvalidUserKeyException when [userKey] is null, expired or invalid.
95+
*/
96+
public suspend fun listPastes(resultsLimit: Int = 50): List<PasteDetails> {
97+
require(resultsLimit in 1..1000) { "resultsLimit should be in range of 1 to 1000" }
98+
val out = sendRequest(API_URL_POST, true) {
6499
append("api_option", "list")
65-
if (resultsLimit != null)
66-
append("api_results_limit", resultsLimit.toString())
100+
append("api_results_limit", resultsLimit.toString())
67101
}
68102
if (out == "No pastes found.")
69103
return listOf()
70104
return PasteDetails.parseList(out)
71105
}
72106

73-
public suspend fun deletePaste(userKey: String, pasteKey: String) {
74-
val out = sendRequest(API_URL_POST) {
107+
/**
108+
* Deletes a paste by its [pasteKey] created by this user.
109+
*
110+
* @throws InvalidUserKeyException when [userKey] is null, expired or invalid.
111+
* @throws PasteNotFoundException when no paste with such [pasteKey] is found.
112+
*/
113+
public suspend fun deletePaste(pasteKey: String) {
114+
val out = sendRequest(API_URL_POST, true) {
75115
append("api_option", "delete")
76-
append("api_user_key", userKey)
77116
append("api_paste_key", pasteKey)
78117
}
79118
if (out != "Paste Removed")
80119
throw PastebinException(out)
81120
}
82121

83-
public suspend fun getUserDetails(userKey: String): UserDetails {
122+
/**
123+
* Gets detailed information about this user.
124+
*
125+
* @throws InvalidUserKeyException when [userKey] is null, expired or invalid.
126+
*/
127+
public suspend fun getUserDetails(): UserDetails {
84128
return UserDetails.parse(
85-
sendRequest(API_URL_POST) {
129+
sendRequest(API_URL_POST, true) {
86130
append("api_option", "userdetails")
87-
append("api_user_key", userKey)
88131
}
89132
)
90133
}
91134

92-
public suspend fun getPaste(userKey: String, pasteKey: String): String {
93-
return sendRequest(API_URL_RAW) {
135+
/**
136+
* Gets text of a paste by its [pasteKey].
137+
*
138+
* @see net.pearx.kpastebin.getPaste
139+
*
140+
* @throws InvalidUserKeyException when [userKey] is null, expired or invalid.
141+
* @throws PasteNotFoundException when no paste with such [pasteKey] is found.
142+
*/
143+
public suspend fun getPaste(pasteKey: String): String {
144+
return sendRequest(API_URL_RAW, true) {
94145
append("api_option", "show_paste")
95-
append("api_user_key", userKey)
96146
append("api_paste_key", pasteKey)
97147
}
98148
}

‎src/commonMain/kotlin/net/pearx/kpastebin/PastebinExceptions.kt

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,35 @@ package net.pearx.kpastebin
22

33
import net.pearx.kpastebin.model.Privacy
44

5+
/** Thrown by [PastebinClient] when provided user key is invalid, expired or null. */
56
public class InvalidUserKeyException(message: String, cause: Throwable? = null) : PastebinException(message, cause)
67

8+
/** Thrown by [PastebinClient] when paste limit with specified [privacy] for current user is exceeded. */
79
public class FreePasteLimitException(public val privacy: Privacy, message: String, cause: Throwable? = null) : PastebinException(message, cause)
10+
11+
/** Thrown by [PastebinClient] when paste text exceeds the size limit. */
812
public class PasteSizeException(message: String, cause: Throwable? = null) : PastebinException(message, cause)
13+
14+
/** Thrown by [PastebinClient] when trying to create a paste with empty text. */
915
public class EmptyPasteException(message: String, cause: Throwable? = null) : PastebinException(message, cause)
16+
17+
/**
18+
* Thrown by [PastebinClient] when specified paste syntax highlighting format doesn't exist.
19+
* Please see [Pastebin documentation](https://pastebin.com/doc_api#5) for the list of available paste formats.
20+
*/
1021
public class InvalidPasteFormatException(message: String, cause: Throwable? = null) : PastebinException(message, cause)
1122

23+
/** Thrown by [PastebinClient] when provided login/password combination is invalid. */
1224
public class InvalidLoginException(message: String, cause: Throwable? = null) : PastebinException(message, cause)
13-
public class AccountNotActiveException(message: String, cause: Throwable? = null) : PastebinException(message, cause)
1425

15-
public class InvalidPermissionException(message: String, cause: Throwable? = null) : PastebinException(message, cause)
26+
/** Thrown by [PastebinClient] when used account isn't active. */
27+
public class AccountNotActiveException(message: String, cause: Throwable? = null) : PastebinException(message, cause)
1628

29+
/** Thrown by [PastebinClient] when paste with specified key doesn't exist or you don't have permissions to view or delete it. */
1730
public class PasteNotFoundException(message: String, cause: Throwable? = null) : PastebinException(message, cause)
1831

32+
/** Thrown by [PastebinClient] when paste publication limit for current IP per day is exceeded. */
1933
public class PastePerDayLimitException(message: String, cause: Throwable? = null) : PastebinException(message, cause)
2034

35+
/** Generic Pastebin exception thrown by [PastebinClient]. */
2136
public open class PastebinException(message: String, cause: Throwable? = null) : RuntimeException(message, cause)

‎src/commonMain/kotlin/net/pearx/kpastebin/PastebinGuest.kt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,11 @@ import io.ktor.http.takeFrom
55
import net.pearx.kpastebin.internal.Http
66
import net.pearx.kpastebin.internal.URL_RAW
77

8+
/**
9+
* Gets Pastebin paste text by its [pasteKey] anonymously.
10+
*
11+
* @see PastebinClient.getPaste
12+
*/
813
public suspend fun getPaste(pasteKey: String): String? {
914
return Http.get<String> { url.takeFrom("$URL_RAW/$pasteKey") }
1015
}

‎src/commonMain/kotlin/net/pearx/kpastebin/internal/ExceptionHelper.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ internal fun checkPastebinResponse(response: String) {
1919
"invalid or expired api_user_key" -> InvalidUserKeyException(sub)
2020
"invalid login" -> InvalidLoginException(sub)
2121
"account not active" -> AccountNotActiveException(sub)
22-
"invalid permission to remove paste" -> InvalidPermissionException(sub)
22+
"invalid permission to remove paste" -> PasteNotFoundException(sub)
2323
"invalid permission to view this paste or invalid api_paste_key" -> PasteNotFoundException(sub)
2424
else -> PastebinException(sub)
2525
}

‎src/commonMain/kotlin/net/pearx/kpastebin/model/AccountType.kt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
package net.pearx.kpastebin.model
22

33
/**
4-
* The list of Pastebin account types
4+
* The list of Pastebin account types.
55
*/
66
public enum class AccountType {
7-
/** Free basic account */
7+
/** Free basic account. */
88
NORMAL,
99

10-
/** Paid pro account */
10+
/** Paid pro account. */
1111
PRO;
1212
}

‎src/commonMain/kotlin/net/pearx/kpastebin/model/ExpireDate.kt

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,34 @@
11
package net.pearx.kpastebin.model
22

33
/**
4-
* The list of possible Pastebin paste expire durations
4+
* The list of possible Pastebin paste expire durations.
55
*/
66
public enum class ExpireDate(internal val code: String) {
7-
/** Paste will never expire */
7+
/** Paste will never expire. */
88
NEVER("N"),
99

10-
/** Paste will expire in 10 minutes after publication */
10+
/** Paste will expire in 10 minutes after publication. */
1111
TEN_MINUTES("10M"),
1212

13-
/** Paste will expire in a hour after publication */
13+
/** Paste will expire in a hour after publication. */
1414
ONE_HOUR("1H"),
1515

16-
/** Paste will expire in a day after publication */
16+
/** Paste will expire in a day after publication. */
1717
ONE_DAY("1D"),
1818

19-
/** Paste will expire in a week after publication */
19+
/** Paste will expire in a week after publication. */
2020
ONE_WEEK("1W"),
2121

22-
/** Paste will expire in two weeks after publication */
22+
/** Paste will expire in two weeks after publication. */
2323
TWO_WEEEKS("2W"),
2424

25-
/** Paste will expire in a month after publication */
25+
/** Paste will expire in a month after publication. */
2626
ONE_MONTH("1M"),
2727

28-
/** Paste will expire in six months after publication */
28+
/** Paste will expire in six months after publication. */
2929
SIX_MONTHS("6M"),
3030

31-
/** Paste will expire in a year after publication */
31+
/** Paste will expire in a year after publication. */
3232
ONE_YEAR("1Y");
3333

3434
internal companion object {

‎src/commonMain/kotlin/net/pearx/kpastebin/model/PasteDetails.kt

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,28 +4,28 @@ import net.pearx.kpastebin.internal.XML_PARENT_REGEX
44
import net.pearx.kpastebin.internal.XML_PROPERTY_REGEX
55

66
/**
7-
* A detailed Pastebin paste information
7+
* A detailed Pastebin paste information.
88
*/
99
public data class PasteDetails(
10-
/** Paste key */
10+
/** Paste key. */
1111
val key: String,
12-
/** Paste publication date */
12+
/** Paste publication date. */
1313
val date: Int,
14-
/** Paste title */
14+
/** Paste title. */
1515
val title: String,
16-
/** Paste size in bytes */
16+
/** Paste size in bytes. */
1717
val size: Int,
18-
/** Paste expiration date */ // todo
18+
/** Paste expiration date. */ // todo
1919
val expireDate: Int,
20-
/** Paste privacy status */
20+
/** Paste privacy status. */
2121
val privacy: Privacy,
22-
/** Paste syntax highlighting language in a user-readable format (e.g., Kotlin or C#) */
22+
/** Paste syntax highlighting language in a user-readable format (e.g., Kotlin or C#). */
2323
val formatLong: String,
24-
/** Paste syntax highlighting language in a short format (e.g. kotlin or csharp) */
24+
/** Paste syntax highlighting language in a short format (e.g. kotlin or csharp). */
2525
val formatShort: String,
26-
/** Paste URL */
26+
/** Paste URL. */
2727
val url: String,
28-
/** Paste views count */
28+
/** Paste view count. */
2929
val hits: Int
3030
) {
3131
internal companion object {

0 commit comments

Comments
 (0)