Merge pull request #282 from pilcrowonpaper/next

Release v3.4.0

Author: pilcrowonpaper

.RELEASE.md

@@ -0,0 +1,4 @@
+- Add Kick provider ([#277](https://github.com/pilcrowonpaper/arctic/pull/277)).
+- Add DonationAlerts provider ([#281](https://github.com/pilcrowonpaper/arctic/pull/281)).
+- Add MercadoLibre provider ([#279](https://github.com/pilcrowonpaper/arctic/pull/279)).
+- Add MercadoPago provider ([#279](https://github.com/pilcrowonpaper/arctic/pull/279)).

README.md

@@ -44,6 +44,7 @@ Arctic does not strictly follow semantic versioning. While we aim to only introd
 - Bungie
 - Coinbase
 - Discord
+- DonationAlerts
 - Dribbble
 - Dropbox
 - Etsy
@@ -56,10 +57,14 @@ Arctic does not strictly follow semantic versioning. While we aim to only introd
 - Google
 - Intuit
 - Kakao
+- KeyCloak
+- Kick
 - Lichess
 - Line
 - Linear
 - LinkedIn
+- MercadoLibre
+- MercadoPago
 - Microsoft Entra ID
 - MyAnimeList
 - Naver

docs/malta.config.json

@@ -30,6 +30,7 @@
 				["Bungie", "/providers/bungie"],
 				["Coinbase", "/providers/coinbase"],
 				["Discord", "/providers/discord"],
+				["DonationAlerts", "/providers/donation-alerts"],
 				["Dribbble", "/providers/dribbble"],
 				["Dropbox", "/providers/dropbox"],
 				["Epic Games", "/providers/epicgames"],
@@ -43,10 +44,13 @@
 				["Intuit", "/providers/intuit"],
 				["Kakao", "/providers/kakao"],
 				["KeyCloak", "/providers/keycloak"],
+				["Kick", "/providers/kick"],
 				["Lichess", "/providers/lichess"],
 				["Line", "/providers/line"],
 				["Linear", "/providers/linear"],
 				["LinkedIn", "/providers/linkedin"],
+				["MercadoLibre", "/providers/mercadolibre"],
+				["MercadoPago", "/providers/mercadopago"],
 				["Microsoft Entra ID", "/providers/microsoft-entra-id"],
 				["MyAnimeList", "/providers/myanimelist"],
 				["Naver", "/providers/naver"],

docs/pages/providers/donation-alerts.md

@@ -0,0 +1,95 @@
+---
+title: "DonationAlerts"
+---
+
+# DonationAlerts
+
+OAuth 2.0 provider for DonationAlerts.
+
+Also see the [OAuth 2.0](/guides/oauth2) guide.
+
+## Initialization
+
+```ts
+import * as arctic from "arctic";
+
+const donationAlerts = new arctic.DonationAlerts(clientId, clientSecret, redirectURI);
+```
+
+## Create authorization URL
+
+```ts
+import * as arctic from "arctic";
+
+const state = arctic.generateState();
+const scopes = ["oauth-user-show"];
+const url = donationAlerts.createAuthorizationURL(state, scopes);
+```
+
+## Validate authorization code
+
+`validateAuthorizationCode()` will either return an [`OAuth2Tokens`](/reference/main/OAuth2Tokens), or throw one of [`OAuth2RequestError`](/reference/main/OAuth2RequestError), [`ArcticFetchError`](/reference/main/ArcticFetchError), [`UnexpectedResponseError`](/reference/main/UnexpectedResponseError), or [`UnexpectedErrorResponseBodyError`](/reference/main/UnexpectedErrorResponseBodyError). DonationAlerts returns an access token, the access token expiration, and a refresh token.
+
+```ts
+import * as arctic from "arctic";
+
+try {
+	const tokens = await donationAlerts.validateAuthorizationCode(code);
+	const accessToken = tokens.accessToken();
+	const accessTokenExpiresAt = tokens.accessTokenExpiresAt();
+	const refreshToken = tokens.refreshToken();
+} catch (e) {
+	if (e instanceof arctic.OAuth2RequestError) {
+		// Invalid authorization code, credentials, or redirect URI
+		const code = e.code;
+		// ...
+	}
+	if (e instanceof arctic.ArcticFetchError) {
+		// Failed to call `fetch()`
+		const cause = e.cause;
+		// ...
+	}
+	// Parse error
+}
+```
+
+## Refresh access tokens
+
+Use `refreshAccessToken()` to get a new access token using a refresh token. DonationAlerts returns the same values as during the authorization code validation. This method also returns `OAuth2Tokens` and throws the same errors as `validateAuthorizationCode()`
+
+```ts
+import * as arctic from "arctic";
+
+try {
+	const scopes = ["oauth-user-show"];
+	const tokens = await donationAlerts.refreshAccessToken(refreshToken, scopes);
+	const accessToken = tokens.accessToken();
+	const accessTokenExpiresAt = tokens.accessTokenExpiresAt();
+} catch (e) {
+	if (e instanceof arctic.OAuth2RequestError) {
+		// Invalid authorization code, credentials, or redirect URI
+	}
+	if (e instanceof arctic.ArcticFetchError) {
+		// Failed to call `fetch()`
+	}
+	// Parse error
+}
+```
+
+### Get user profile
+
+Add the `oauth-user-show` scope and use the [`/user/oauth`](https://www.donationalerts.com/apidoc#api_v1__users__user_profile_information) endpoint.
+
+```ts
+const scopes = ["oauth-user-show"];
+const url = donationAlerts.createAuthorizationURL(state, scopes);
+```
+
+```ts
+const response = await fetch("https://www.donationalerts.com/api/v1/user/oauth", {
+	headers: {
+		Authorization: `Bearer ${accessToken}`
+	}
+});
+const user = await response.json();
+```

docs/pages/providers/kick.md

@@ -0,0 +1,117 @@
+---
+title: "Kick"
+---
+
+# Kick
+
+OAuth 2.0 provider for Kick.
+
+Also see the [OAuth 2.0 with PKCE](/guides/oauth2-pkce) guide.
+
+## Initialization
+
+```ts
+import * as arctic from "arctic";
+
+const kick = new arctic.Kick(clientId, clientSecret, redirectURI);
+```
+
+## Create authorization URL
+
+```ts
+import * as arctic from "arctic";
+
+const state = arctic.generateState();
+const codeVerifier = arctic.generateCodeVerifier();
+const scopes = ["user:read"];
+const url = kick.createAuthorizationURL(state, codeVerifier, scopes);
+```
+
+## Validate authorization code
+
+`validateAuthorizationCode()` will either return an [`OAuth2Tokens`](/reference/main/OAuth2Tokens), or throw one of [`OAuth2RequestError`](/reference/main/OAuth2RequestError), [`ArcticFetchError`](/reference/main/ArcticFetchError), [`UnexpectedResponseError`](/reference/main/UnexpectedResponseError), or [`UnexpectedErrorResponseBodyError`](/reference/main/UnexpectedErrorResponseBodyError). Kick returns an access token, the access token expiration, and a refresh token.
+
+```ts
+import * as arctic from "arctic";
+
+try {
+	const tokens = await kick.validateAuthorizationCode(code, codeVerifier);
+	const accessToken = tokens.accessToken();
+	const accessTokenExpiresAt = tokens.accessTokenExpiresAt();
+	const refreshToken = tokens.refreshToken();
+} catch (e) {
+	if (e instanceof arctic.OAuth2RequestError) {
+		// Invalid authorization code, credentials, or redirect URI
+		const code = e.code;
+		// ...
+	}
+	if (e instanceof arctic.ArcticFetchError) {
+		// Failed to call `fetch()`
+		const cause = e.cause;
+		// ...
+	}
+	// Parse error
+}
+```
+
+## Refresh access tokens
+
+Use `refreshAccessToken()` to get a new access token using a refresh token. Kick returns the same values as during the authorization code validation. This method also returns `OAuth2Tokens` and throws the same errors as `validateAuthorizationCode()`
+
+```ts
+import * as arctic from "arctic";
+
+try {
+	const tokens = await kick.refreshAccessToken(refreshToken);
+	const accessToken = tokens.accessToken();
+	const accessTokenExpiresAt = tokens.accessTokenExpiresAt();
+} catch (e) {
+	if (e instanceof arctic.OAuth2RequestError) {
+		// Invalid authorization code, credentials, or redirect URI
+	}
+	if (e instanceof arctic.ArcticFetchError) {
+		// Failed to call `fetch()`
+	}
+	// Parse error
+}
+```
+
+### Get user profile
+
+Add the `user:read` scope when creating the authorization URL.
+
+```ts
+const scopes = ["user:read"];
+const url = kick.createAuthorizationURL(state, codeVerifier, scopes);
+```
+
+Then make a request to the Kick REST API with the access token.
+
+```ts
+const tokens = await kick.validateAuthorizationCode(code, codeVerifier);
+
+const response = await fetch("https://api.kick.com/public/v1/users", {
+	headers: {
+		Authorization: `Bearer ${tokens.accessToken()}`
+	}
+});
+const user = await response.json();
+```
+
+## Revoke tokens
+
+Pass a token to `revokeToken()` to revoke all tokens associated with the authorization. This can throw the same errors as `validateAuthorizationCode()`.
+
+```ts
+try {
+	await kick.revokeToken(refreshToken);
+} catch (e) {
+	if (e instanceof arctic.OAuth2RequestError) {
+		// Invalid authorization code, credentials, or redirect URI
+	}
+	if (e instanceof arctic.ArcticFetchError) {
+		// Failed to call `fetch()`
+	}
+	// Parse error
+}
+```

docs/pages/providers/mercadolibre.md

@@ -0,0 +1,96 @@
+---
+title: "Mercado Libre"
+---
+
+# Mercado Libre
+
+OAuth 2.0 provider for Mercado Libre. This client requires PKCE to be enabled in your application settings.
+
+Also see the [OAuth 2.0 with PKCE](/guides/oauth2-pkce) guide.
+
+## Initialization
+
+```ts
+import * as arctic from "arctic";
+
+const mercadolibre = new arctic.MercadoLibre(clientId, clientSecret, redirectURI);
+```
+
+## Create authorization URL
+
+```ts
+import * as arctic from "arctic";
+
+const state = arctic.generateState();
+const url = mercadolibre.createAuthorizationURL(state);
+```
+
+## Validate authorization code
+
+`validateAuthorizationCode()` will either return an [`OAuth2Tokens`](/reference/main/OAuth2Tokens), or throw one of [`OAuth2RequestError`](/reference/main/OAuth2RequestError), [`ArcticFetchError`](/reference/main/ArcticFetchError), [`UnexpectedResponseError`](/reference/main/UnexpectedResponseError), or [`UnexpectedErrorResponseBodyError`](/reference/main/UnexpectedErrorResponseBodyError). Mercado Libre returns an access token, its expiration, and a refresh token.
+
+```ts
+import * as arctic from "arctic";
+
+try {
+	const tokens = await mercadolibre.validateAuthorizationCode(code);
+	const accessToken = tokens.accessToken();
+	const accessTokenExpiresAt = tokens.accessTokenExpiresAt();
+	const refreshToken = tokens.refreshToken();
+} catch (e) {
+	if (e instanceof arctic.OAuth2RequestError) {
+		// Invalid authorization code, credentials, or redirect URI
+		const code = e.code;
+		// ...
+	}
+	if (e instanceof arctic.ArcticFetchError) {
+		// Failed to call `fetch()`
+		const cause = e.cause;
+		// ...
+	}
+	// Parse error
+}
+```
+
+## Refresh access tokens
+
+Add the `offline_access` scope to get a refresh token.
+
+```ts
+const tokens = await mercadolibre.validateAuthorizationCode(code, codeVerifier);
+const refreshToken = tokens.refreshToken();
+```
+
+Use `refreshAccessToken()` to get a new access token using a refresh token. Mercado Libre returns the same values as during the authorization code validation. This method also returns `OAuth2Tokens` and throws the same errors as `validateAuthorizationCode()`
+
+```ts
+import * as arctic from "arctic";
+
+try {
+	const tokens = await mercadolibre.refreshAccessToken(refreshToken);
+	const accessToken = tokens.accessToken();
+	const accessTokenExpiresAt = tokens.accessTokenExpiresAt();
+	const refreshToken = tokens.refreshToken();
+} catch (e) {
+	if (e instanceof arctic.OAuth2RequestError) {
+		// Invalid authorization code, credentials, or redirect URI
+	}
+	if (e instanceof arctic.ArcticFetchError) {
+		// Failed to call `fetch()`
+	}
+	// Parse error
+}
+```
+
+## Get user profile
+
+Use the [`/users/me` endpoint](https://developers.mercadolibre.com.ar/es_ar/consulta-usuarios#Consultar-mis-datos-personales).
+
+```ts
+const response = await fetch("https://api.mercadolibre.com/users/me", {
+	headers: {
+		Authorization: `Bearer ${accessToken}`
+	}
+});
+const user = await response.json();
+```