-
-# Soundify exapmle (node-express-auth)
-
-// TODO
diff --git a/examples/node-express-auth/package.json b/examples/node-express-auth/package.json
deleted file mode 100644
index 602b4c4..0000000
--- a/examples/node-express-auth/package.json
+++ /dev/null
@@ -1,19 +0,0 @@
-{
- "name": "@examples/node-express-auth",
- "private": "true",
- "type": "module",
- "scripts": {
- "dev": "tsc && node ./dist/main.js"
- },
- "devDependencies": {
- "@types/cookie-parser": "1.4.3",
- "@types/express": "4.17.17",
- "@types/node": "latest",
- "typescript": "5.1.3"
- },
- "dependencies": {
- "cookie-parser": "1.4.6",
- "express": "4.18.2",
- "@soundify/web-api": "workspace:*"
- }
-}
diff --git a/examples/node-express-auth/src/main.ts b/examples/node-express-auth/src/main.ts
deleted file mode 100644
index 3be2081..0000000
--- a/examples/node-express-auth/src/main.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-import { AuthCodeFlow } from "@soundify/web-api";
-import { randomUUID } from "node:crypto";
-import express from "express";
-import cookieParser from "cookie-parser";
-
-const app = express();
-app.use(cookieParser("secret"));
-
-const env = {
- client_id: process.env.SPOTIFY_CLIENT_ID!,
- client_secret: process.env.SPOTIFY_CLIENT_SECRET!,
- redirect_uri: process.env.SPOTIFY_REDIRECT_URI!
-};
-
-const authFlow = new AuthCodeFlow({
- client_id: env.client_id,
- client_secret: env.client_secret
-});
-
-app.get("/login", (_, res) => {
- const state = randomUUID();
-
- res.cookie("state", state, {
- httpOnly: true
- });
- res.redirect(
- authFlow
- .getAuthURL({
- scopes: ["user-read-email"],
- state,
- redirect_uri: env.redirect_uri
- })
- .toString()
- );
-});
-
-app.get("/callback", async (req, res) => {
- try {
- const searchParams = new URL(req.url, `http://${req.headers.host}`)
- .searchParams;
- const data = AuthCodeFlow.parseCallbackData(searchParams);
- if ("error" in data) {
- throw new Error(data.error);
- }
-
- const storedState = req.cookies["state"];
- if (!storedState || !data.state || storedState !== data.state) {
- throw new Error("Unable to verify request with state.");
- }
-
- const grantData = await authFlow.getGrantData(env.redirect_uri, data.code);
-
- res.status(200).json(grantData);
- } catch (error) {
- res.status(400).send(String(error));
- }
-});
-
-const port = process.env.PORT;
-app.listen(port, () => {
- console.log(
- `To get OAuth tokens, navigate to: http://localhost:${port}/login`
- );
-});
diff --git a/examples/node-express-auth/tsconfig.json b/examples/node-express-auth/tsconfig.json
deleted file mode 100644
index 8baaccc..0000000
--- a/examples/node-express-auth/tsconfig.json
+++ /dev/null
@@ -1,16 +0,0 @@
-{
- "compilerOptions": {
- "forceConsistentCasingInFileNames": true,
- "allowSyntheticDefaultImports": true,
- "noFallthroughCasesInSwitch": true,
- "noImplicitReturns": true,
- "noUnusedParameters": true,
- "strict": true,
- "declaration": true,
- "moduleResolution": "node",
- "module": "ESNext",
- "rootDir": "./src/",
- "outDir": "./dist/",
- "target": "ESNext"
- }
-}
diff --git a/examples/oauth/auth_code.ts b/examples/oauth/auth_code.ts
new file mode 100644
index 0000000..a2d46cb
--- /dev/null
+++ b/examples/oauth/auth_code.ts
@@ -0,0 +1,165 @@
+import * as oauth from "oauth4webapi";
+import { OAUTH_SCOPES, SPOTIFY_AUTH_URL } from "@soundify/web-api";
+import { z } from "zod";
+import { load } from "std/dotenv/mod.ts";
+import { encodeBase64Url } from "std/encoding/base64url.ts";
+import { Application, Router } from "oak";
+
+await load({ export: true });
+
+const env = z
+ .object({
+ SPOTIFY_CLIENT_ID: z.string(),
+ SPOTIFY_CLIENT_SECRET: z.string(),
+ SPOTIFY_REDIRECT_URI: z.string().url(),
+ })
+ .parse(Deno.env.toObject());
+
+const issuer = new URL(SPOTIFY_AUTH_URL);
+const authServer = await oauth.processDiscoveryResponse(
+ issuer,
+ await oauth.discoveryRequest(issuer),
+);
+
+const oauthClient: oauth.Client = {
+ client_id: env.SPOTIFY_CLIENT_ID,
+ client_secret: env.SPOTIFY_CLIENT_SECRET,
+ token_endpoint_auth_method: "client_secret_basic",
+};
+
+const app = new Application();
+const router = new Router();
+
+router.get("/login", async (ctx) => {
+ const state = oauth.generateRandomState();
+ await ctx.cookies.set("state", state, {
+ httpOnly: true,
+ path: "/callback",
+ });
+
+ const authUrl = new URL(authServer.authorization_endpoint!);
+ authUrl.searchParams.set("client_id", env.SPOTIFY_CLIENT_ID);
+ authUrl.searchParams.set("redirect_uri", env.SPOTIFY_REDIRECT_URI);
+ authUrl.searchParams.set("response_type", "code");
+ authUrl.searchParams.set("state", state);
+ authUrl.searchParams.set("scope", Object.values(OAUTH_SCOPES).join(" "));
+
+ return ctx.response.redirect(authUrl);
+});
+
+router.get("/callback", async (ctx) => {
+ try {
+ const state = await ctx.cookies.get("state");
+ if (!state) {
+ ctx.response.status = 400;
+ ctx.response.body = "Missing state cookie";
+ return;
+ }
+
+ const params = oauth.validateAuthResponse(
+ authServer,
+ oauthClient,
+ ctx.request.url,
+ state,
+ );
+ if (oauth.isOAuth2Error(params)) {
+ throw new Error(
+ params.error + params.error_description
+ ? " : " + params.error_description
+ : "",
+ );
+ }
+
+ const response = await fetch(new URL("/api/token", SPOTIFY_AUTH_URL), {
+ method: "POST",
+ body: new URLSearchParams({
+ grant_type: "authorization_code",
+ redirect_uri: env.SPOTIFY_REDIRECT_URI,
+ code: params.get("code")!,
+ }),
+ headers: {
+ Authorization: "Basic " +
+ encodeBase64Url(
+ env.SPOTIFY_CLIENT_ID + ":" + env.SPOTIFY_CLIENT_SECRET,
+ ),
+ },
+ });
+
+ const result = await oauth.processAuthorizationCodeOAuth2Response(
+ authServer,
+ oauthClient,
+ response,
+ );
+
+ if (oauth.isOAuth2Error(result)) {
+ throw new Error(
+ result.error + result.error_description
+ ? " : " + result.error_description
+ : "",
+ );
+ }
+
+ if (!result.refresh_token) {
+ throw new Error("Missing refresh token");
+ }
+
+ await ctx.cookies.set("refresh_token", result.refresh_token, {
+ httpOnly: true,
+ path: "/refresh",
+ });
+
+ ctx.response.type = "application/json";
+ ctx.response.body = JSON.stringify(result);
+ ctx.response.status = 200;
+ } catch (error) {
+ console.log(error);
+ ctx.response.status = 500;
+ ctx.response.body = error.message;
+ } finally {
+ await ctx.cookies.set("state", null, {
+ httpOnly: true,
+ path: "/callback",
+ });
+ }
+});
+
+router.get("/refresh", async (ctx) => {
+ const refreshToken = await ctx.cookies.get("refresh_token");
+ if (!refreshToken) {
+ ctx.response.status = 400;
+ ctx.response.body = "Missing refresh token";
+ return;
+ }
+
+ const res = await oauth.refreshTokenGrantRequest(
+ authServer,
+ oauthClient,
+ refreshToken,
+ );
+ const result = await oauth.processRefreshTokenResponse(
+ authServer,
+ oauthClient,
+ res,
+ );
+
+ if (oauth.isOAuth2Error(result)) {
+ ctx.response.status = 500;
+ ctx.response.body = result.error + result.error_description
+ ? " : " + result.error_description
+ : "";
+ return;
+ }
+
+ ctx.response.type = "application/json";
+ ctx.response.body = JSON.stringify(result);
+ ctx.response.status = 200;
+});
+
+app.use(router.routes());
+app.use(router.allowedMethods());
+
+app.addEventListener(
+ "listen",
+ (event) => console.log(`http://${event.hostname}:${event.port}/login`),
+);
+await app.listen({ port: 3000 });
diff --git a/examples/oauth/client_credentials.ts b/examples/oauth/client_credentials.ts
new file mode 100644
index 0000000..c3b5b3c
--- /dev/null
+++ b/examples/oauth/client_credentials.ts
@@ -0,0 +1,55 @@
+import * as oauth from "oauth4webapi";
+import { SPOTIFY_AUTH_URL } from "@soundify/web-api";
+import { z } from "zod";
+import { load } from "std/dotenv/mod.ts";
+import { search, SpotifyClient } from "@soundify/web-api";
+
+await load({ export: true });
+
+const env = z
+ .object({
+ SPOTIFY_CLIENT_ID: z.string(),
+ SPOTIFY_CLIENT_SECRET: z.string(),
+ })
+ .parse(Deno.env.toObject());
+
+const issuer = new URL(SPOTIFY_AUTH_URL);
+const authServer = await oauth.processDiscoveryResponse(
+ issuer,
+ await oauth.discoveryRequest(issuer),
+);
+
+const oauthClient: oauth.Client = {
+ client_id: env.SPOTIFY_CLIENT_ID,
+ client_secret: env.SPOTIFY_CLIENT_SECRET,
+ token_endpoint_auth_method: "client_secret_basic",
+};
+
+const refresher = async () => {
+ const res = await oauth.clientCredentialsGrantRequest(
+ authServer,
+ oauthClient,
+ {},
+ );
+
+ const result = await oauth.processClientCredentialsResponse(
+ authServer,
+ oauthClient,
+ res,
+ );
+ if (oauth.isOAuth2Error(result)) {
+ throw new Error(
+ result.error + result.error_description
+ ? " : " + result.error_description
+ : "",
+ );
+ }
+ return result.access_token;
+};
+
+const accessToken = await refresher();
+
+const spotifyClient = new SpotifyClient(accessToken);
+
+const result = await search(spotifyClient, "track", "Never Gonna Give You Up");
+console.log(result.tracks.items.at(0));
diff --git a/examples/oauth/pkce_code.ts b/examples/oauth/pkce_code.ts
new file mode 100644
index 0000000..1d117ef
--- /dev/null
+++ b/examples/oauth/pkce_code.ts
@@ -0,0 +1,121 @@
+import * as oauth from "oauth4webapi";
+import {
+ getCurrentUser,
+ OAUTH_SCOPES,
+ SPOTIFY_AUTH_URL,
+ SpotifyClient,
+} from "@soundify/web-api";
+import { z } from "zod";
+import { load } from "std/dotenv/mod.ts";
+import { Application, Router } from "oak";
+
+await load({ export: true });
+
+const env = z
+ .object({
+ SPOTIFY_CLIENT_ID: z.string(),
+ SPOTIFY_REDIRECT_URI: z.string().url(),
+ })
+ .parse(Deno.env.toObject());
+
+const issuer = new URL(SPOTIFY_AUTH_URL);
+const authServer = await oauth.processDiscoveryResponse(
+ issuer,
+ await oauth.discoveryRequest(issuer),
+);
+
+const oauthClient: oauth.Client = {
+ client_id: env.SPOTIFY_CLIENT_ID,
+ token_endpoint_auth_method: "client_secret_basic",
+};
+
+const app = new Application();
+const router = new Router();
+
+router.get("/login", async (ctx) => {
+ const codeVerifier = oauth.generateRandomCodeVerifier();
+ const codeChallenge = await oauth.calculatePKCECodeChallenge(codeVerifier);
+
+ await ctx.cookies.set("code_verifier", codeVerifier, {
+ httpOnly: true,
+ path: "/callback",
+ });
+
+ const authUrl = new URL(authServer.authorization_endpoint!);
+ authUrl.searchParams.set("client_id", env.SPOTIFY_CLIENT_ID);
+ authUrl.searchParams.set("redirect_uri", env.SPOTIFY_REDIRECT_URI);
+ authUrl.searchParams.set("response_type", "code");
+ authUrl.searchParams.set("code_challenge", codeChallenge);
+ authUrl.searchParams.set("code_challenge_method", "S256");
+ authUrl.searchParams.set(
+ "scope",
+ Object.values(OAUTH_SCOPES).join(" "),
+ );
+
+ return ctx.response.redirect(authUrl);
+});
+
+router.get("/callback", async (ctx) => {
+ try {
+ const params = oauth.validateAuthResponse(
+ authServer,
+ oauthClient,
+ ctx.request.url,
+ oauth.expectNoState,
+ );
+ if (oauth.isOAuth2Error(params)) {
+ throw new Error(
+ params.error + params.error_description
+ ? " : " + params.error_description
+ : "",
+ );
+ }
+
+ const codeVerifier = await ctx.cookies.get("code_verifier");
+ if (!codeVerifier) {
+ throw new Error("no code verifier");
+ }
+
+ const response = await oauth.authorizationCodeGrantRequest(
+ authServer,
+ oauthClient,
+ params,
+ env.SPOTIFY_REDIRECT_URI,
+ codeVerifier,
+ );
+ const result = await oauth.processAuthorizationCodeOAuth2Response(
+ authServer,
+ oauthClient,
+ response,
+ );
+ console.log(result);
+ if (oauth.isOAuth2Error(result)) {
+ throw new Error(result.error);
+ }
+
+ const spotifyClient = new SpotifyClient(result.access_token);
+ const user = await getCurrentUser(spotifyClient);
+
+ ctx.response.type = "application/json";
+ ctx.response.body = JSON.stringify(user);
+ ctx.response.status = 200;
+ } catch (error) {
+ console.log(error);
+ ctx.response.status = 500;
+ ctx.response.body = error.message;
+ } finally {
+ await ctx.cookies.set("code_verifier", null, {
+ httpOnly: true,
+ path: "/callback",
+ });
+ }
+});
+
+app.use(router.routes());
+app.use(router.allowedMethods());
+
+app.addEventListener(
+ "listen",
+ (event) => console.log(`http://${event.hostname}:${event.port}/login`),
+);
+await app.listen({ port: 3000 });
diff --git a/examples/react-implicit-grant/.env.example b/examples/react-implicit-grant/.env.example
deleted file mode 100644
index 34829e3..0000000
--- a/examples/react-implicit-grant/.env.example
+++ /dev/null
@@ -1,2 +0,0 @@
-VITE_SPOTIFY_CLIENT_ID=
-VITE_SPOTIFY_REDIRECT_URI=
\ No newline at end of file
diff --git a/examples/react-implicit-grant/README.md b/examples/react-implicit-grant/README.md
deleted file mode 100644
index f86bd69..0000000
--- a/examples/react-implicit-grant/README.md
+++ /dev/null
@@ -1,5 +0,0 @@
-
-
-# Soundify exapmle (react-implicit-grant)
-
-// TODO
diff --git a/examples/react-implicit-grant/index.html b/examples/react-implicit-grant/index.html
deleted file mode 100644
index 1df520a..0000000
--- a/examples/react-implicit-grant/index.html
+++ /dev/null
@@ -1,14 +0,0 @@
-
-
-
-
-
-
- 
-
-# Soundify exapmle (react-pkce-auth)
-
-This example shows how to use PKCE authentication in a single-page React
-application. We will also use the `react-router-dom`, `@tanstack/react-query`
-libraries to speed up our routine workflow.
-
-Don't forget to fill in the env variables in the `.env` file in the same way as
-in the `.env.example` file.
-
-After logging to your spotify you will see your top artists
-
-
diff --git a/examples/react-pkce-auth/index.html b/examples/react-pkce-auth/index.html
deleted file mode 100644
index f3c41a0..0000000
--- a/examples/react-pkce-auth/index.html
+++ /dev/null
@@ -1,13 +0,0 @@
-
-
-
-
-
-
- Your top artists
--
- {topArtists.items.map((artist) => (
-
-
-
-
{artist.name}
-Popularity: {artist.popularity}
-
- ))}
-
-
- 
-
-
- 
-
-
- 
+
+ 
-
- 
+
+ 
- Soundify is a lightweight and flexible library for seamless communication with Spotify API, designed to work smoothly with TypeScript, Deno, Node.js, and client-side JavaScript. It's open source and provides an easy-to-use interface for accessing Spotify's data. + Soundify is a lightweight and flexible library for interacting with the Spotify API, designed to work seamlessly with TypeScript and support all available runtimes.
+ Getting Started | Authorization | Usage | Contributors +
-- 💻 Multiruntime: Works seamlessly with Node.js, Deno, and the Browser - environment. -- 🚀 Modern: Leverages native web APIs like `fetch`, `crypto`, - `URLSearchParams`, etc. -- 🔑 Comprehensive auth support: It can handle all Spotify Auth flows and - automatically refreshes access token. -- 📦 Lightweight and treeshakable: It is designed with care for your bundle - size. -- 🆎 Strictly typed: All entities returned by the api have exact and up to date - types. -- 📖 Great docs: The library comes with extensive documentation and lots of - examples. +## Installation -# Installation - -## [NPM](https://npmjs.com/package/@soundify/web-api) +The package doesn't depend on runtime specific apis, so you should be able to +use it without any problems everywhere. ```bash -npm i @soundify/web-api +pnpm add @soundify/web-api ``` -## Deno - -```ts -import { ... } from "npm:@soundify/web-api"; -``` - -# Gettings started - -To make your first request with Soundify you need to create a `SpotifyClient`. -As the first parameter it takes access token or -[AuthProvider](#auth-provider-and-automatic-tokens-refreshing). - -```ts -import { SpotifyClient } from "@soundify/web-api"; - -const client = new SpotifyClient("ACCESS_TOKEN"); -``` - -If you've used other api libraries, you can expect something like a bunch of -methods on a single class, but in our case the default recommendation is to use -endpoint functions that take the client as the first argument. In practice, it -looks like this: - -```ts -import { getCurrentUser, SpotifyClient } from "@soundify/web-api"; - -const client = new SpotifyClient("ACCESS_TOKEN"); -const user = await getCurrentUser(client); - -console.log(user); +```bash +bun install @soundify/web-api ``` -If your Access Token is valid it will output something like this - -```js +```jsonc +// deno.json { - "id": "31xofk5q7l22rvsbff7yiechyx6i", - "display_name": "Soundify", - "type": "user", - "uri": "spotify:user:31xofk5q7l22rvsbff7yiechyx6i", - // etc... + "imports": { + "@soundify/web-api": "https://deno.land/x/soundify/mod.ts" + } } ``` -This may be inconvenient for some users, but it was done primarily to allow tree -sharding so that clients don't send a lot of unused code. - -But, if you are writing a backend or don't care about the size of the library -you can use the `createSpotifyAPI()` function which will bind all the endpoint -functions to the client. That way you can use this object throughout your -application and not have to worry about imports. - -```ts -import { createSpotifyAPI, SpotifyClient } from "@soundify/web-api"; - -const api = createSpotifyAPI("ACCESS_TOKEN"); -const user = await api.getCurrentUser(); - -console.log(user); -``` - -# Authorization - -If you have no experience with Spotify Authorization you can read more about it -in the -[Spotify Authorization Guide](https://developer.spotify.com/documentation/web-api/concepts/authorization). - -There are four authorization flows that can be used in Spotify, and all of them -are supported in this library 🔥. The criteria for choosing the right flow for -you are described in the Spotify docs linked above. +## Getting Started -
-
-
-With this flow user grants permission only once, after which you can use refresh
-token to create a new access token. The flow is used on the server because it
-requires SPOTIFY_CLIENT_SECRET, which is not desirable to show to others.
-
-_Pseudo http-server code just for example_
+Soundify has a very simple structure. It consists of a `SpotifyClient` capable
+of making requests to the Spotify API, along with a set of functions (like
+`getCurrentUser`) that utilize the client to make requests to specific
+endpoints.
```ts
-import { AuthCode } from "@soundify/web-api";
+import { getCurrentUser, search, SpotifyClient } from "@soundify/web-api";
-const authFlow = new AuthCode({
- client_id: "YOUR_CLIENT_ID",
- client_secret: "YOUR_CLIENT_SECRET"
-});
-
-const loginHandler = async (req, res) => {
- const authURL = authFlow.getAuthURL({
- redirect_uri: "YOUR_REDIRECT_URI",
- scopes: ["user-read-email"]
- });
- res.redirect(302, authURL.toString());
-};
+const client = new SpotifyClient("YOUR_ACCESS_TOKEN");
-const codeHandler = async (req, res) => {
- try {
- const code = new URL(req.url).searchParams.get("code");
- if (!code) throw new Error("Unable to find 'code'");
-
- const { access_token, refresh_token } = await authFlow.getGrantData(
- "YOUR_REDIRECT_URI",
- code
- );
- res.cookie("refresh_token", refresh_token);
- res.status(200).json({ access_token });
- } catch (err) {
- res.status(500).json({ error: err.message });
- }
-};
+const me = await getCurrentUser(client);
+console.log(me);
-const refreshHandler = async (req, res) => {
- try {
- const { refresh_token } = req.cookies;
- const { access_token } = await authFlow.refresh(refresh_token);
- res.status(200).json({ access_token });
- } catch (err) {
- res.status(500).json({ error: err.message });
- }
-};
+const result = await search(client, "track", "Never Gonna Give You Up");
+console.log(result.tracks.items.at(0));
```
-> It is also recommended to use `state`, which provides protection against
-> attacks such as cross-site request forgery, but in the examples below we will
-> not use it for simplicity.
-
-Real code examples with AuthCode flow:
-
-- [examples/node-express-auth](https://github.com/MellKam/soundify/tree/main/examples/node-express-auth),
-- [examples/next-ssr](https://github.com/MellKam/soundify/tree/main/examples/next-ssr),
-- [examples/deno-oak-auth](https://github.com/MellKam/soundify/tree/main/examples/deno-oak-auth)
-
-
+Compared to the usual OOP way of creating API clients, this approach has several
+advantages. The main one is that it is _tree-shakable_. You only ship code you
+use. This may be not that important for server-side apps, but I'm sure frontend
+users will thank you for not including an extra 10kb of crappy js into your
+bundle.
-Authorization Code flow
-
-With this flow user grants permission only once, after which you can use refresh
-token to create a new access token. The flow is used on the server because it
-requires SPOTIFY_CLIENT_SECRET, which is not desirable to show to others.
-
-_Pseudo http-server code just for example_
+Soundify has a very simple structure. It consists of a `SpotifyClient` capable
+of making requests to the Spotify API, along with a set of functions (like
+`getCurrentUser`) that utilize the client to make requests to specific
+endpoints.
```ts
-import { AuthCode } from "@soundify/web-api";
+import { getCurrentUser, search, SpotifyClient } from "@soundify/web-api";
-const authFlow = new AuthCode({
- client_id: "YOUR_CLIENT_ID",
- client_secret: "YOUR_CLIENT_SECRET"
-});
-
-const loginHandler = async (req, res) => {
- const authURL = authFlow.getAuthURL({
- redirect_uri: "YOUR_REDIRECT_URI",
- scopes: ["user-read-email"]
- });
- res.redirect(302, authURL.toString());
-};
+const client = new SpotifyClient("YOUR_ACCESS_TOKEN");
-const codeHandler = async (req, res) => {
- try {
- const code = new URL(req.url).searchParams.get("code");
- if (!code) throw new Error("Unable to find 'code'");
-
- const { access_token, refresh_token } = await authFlow.getGrantData(
- "YOUR_REDIRECT_URI",
- code
- );
- res.cookie("refresh_token", refresh_token);
- res.status(200).json({ access_token });
- } catch (err) {
- res.status(500).json({ error: err.message });
- }
-};
+const me = await getCurrentUser(client);
+console.log(me);
-const refreshHandler = async (req, res) => {
- try {
- const { refresh_token } = req.cookies;
- const { access_token } = await authFlow.refresh(refresh_token);
- res.status(200).json({ access_token });
- } catch (err) {
- res.status(500).json({ error: err.message });
- }
-};
+const result = await search(client, "track", "Never Gonna Give You Up");
+console.log(result.tracks.items.at(0));
```
-> It is also recommended to use `state`, which provides protection against
-> attacks such as cross-site request forgery, but in the examples below we will
-> not use it for simplicity.
-
-Real code examples with AuthCode flow:
-
-- [examples/node-express-auth](https://github.com/MellKam/soundify/tree/main/examples/node-express-auth),
-- [examples/next-ssr](https://github.com/MellKam/soundify/tree/main/examples/next-ssr),
-- [examples/deno-oak-auth](https://github.com/MellKam/soundify/tree/main/examples/deno-oak-auth)
-
-
-
-
-This thread is similar to AuthCode, but it is handled on the client and
-therefore does not require SPOTIFY_CLIENT_SECRET.
+### Error handling 📛
```ts
-import { PKCEAuthCode } from "@soundify/web-api";
+import { getCurrentUser, SpotifyClient, SpotifyError } from "@soundify/web-api";
-const authFlow = new PKCEAuthCode("YOUR_CLIENT_ID");
+const client = new SpotifyClient("INVALID_ACCESS_TOKEN");
-const authorize = async () => {
- const { code_challenge, code_verifier } = await PKCEAuthCode.generateCodes();
- localStorage.setItem("code_verifier", code_verifier);
+try {
+ const me = await getCurrentUser(client);
+ console.log(me);
+} catch (error) {
+ if (error instanceof SpotifyError) {
+ error.status; // 401
- location.replace(
- authFlow.getAuthURL({
- code_challenge,
- scopes: ["user-read-email"],
- redirect_uri: "YOUR_REDIRECT_URI"
- })
- );
-};
+ const message = typeof error.body === "string"
+ ? error.body
+ : error.body?.error.message;
+ console.error(message); // "Invalid access token"
-const codeHandler = async () => {
- const data = PKCEAuthCode.parseCallbackData(
- new URLSearchParams(location.search)
- );
-
- if ("error" in data) {
- throw new Error(data.error);
- }
-
- const code_verifier = localStorage.getItem("code_verifier");
- if (!code_verifier) {
- throw new Error("Cannot find code_verifier");
- }
-
- const { refresh_token, access_token } = authFlow.getGrantData({
- code: data.code,
- code_verifier,
- redirect_uri: "YOUR_REDIRECT_URI"
- });
-
- localStorage.removeItem("code_verifier");
- localStorage.setItem("refresh_token", refresh_token);
- localStorage.setItem("access_token", access_token);
-};
+ error.response.headers.get("Date"); // You can access the response here
-const refreshHandler = () => {
- const refreshToken = localStorage.getItem("refresh_token");
- const { access_token, refresh_token } = authFlow.refresh(refreshToken);
+ console.error(error);
+ // SpotifyError: 401 Unauthorized (https://api.spotify.com/v1/me) : Invalid access token
+ return;
+ }
- localStorage.setItem("refresh_token", refresh_token);
- localStorage.setItem("access_token", access_token);
-};
+ // If it's not a SpotifyError, then it's some type of network error that fetch throws
+ // Or can be DOMException if you abort the request
+ console.error("We're totally f#%ked!");
+}
```
-Real code examples with PKCEAuthCode flow:
+### Rate Limiting 🕒
-- [examples/react-pkce-auth](https://github.com/MellKam/soundify/tree/main/examples/react-pkce-auth)
+If you're really annoying customer, Spotify may block you for some time. To know
+what time you need to wait, you can use `Retry-After` header, which will tell
+you time in seconds.
+[More about rate limiting↗](https://developer.spotify.com/documentation/web-api/concepts/rate-limits)
-
-
-Authorization Code flow with PKCE
-
-This thread is similar to AuthCode, but it is handled on the client and
-therefore does not require SPOTIFY_CLIENT_SECRET.
+### Error handling 📛
```ts
-import { PKCEAuthCode } from "@soundify/web-api";
+import { getCurrentUser, SpotifyClient, SpotifyError } from "@soundify/web-api";
-const authFlow = new PKCEAuthCode("YOUR_CLIENT_ID");
+const client = new SpotifyClient("INVALID_ACCESS_TOKEN");
-const authorize = async () => {
- const { code_challenge, code_verifier } = await PKCEAuthCode.generateCodes();
- localStorage.setItem("code_verifier", code_verifier);
+try {
+ const me = await getCurrentUser(client);
+ console.log(me);
+} catch (error) {
+ if (error instanceof SpotifyError) {
+ error.status; // 401
- location.replace(
- authFlow.getAuthURL({
- code_challenge,
- scopes: ["user-read-email"],
- redirect_uri: "YOUR_REDIRECT_URI"
- })
- );
-};
+ const message = typeof error.body === "string"
+ ? error.body
+ : error.body?.error.message;
+ console.error(message); // "Invalid access token"
-const codeHandler = async () => {
- const data = PKCEAuthCode.parseCallbackData(
- new URLSearchParams(location.search)
- );
-
- if ("error" in data) {
- throw new Error(data.error);
- }
-
- const code_verifier = localStorage.getItem("code_verifier");
- if (!code_verifier) {
- throw new Error("Cannot find code_verifier");
- }
-
- const { refresh_token, access_token } = authFlow.getGrantData({
- code: data.code,
- code_verifier,
- redirect_uri: "YOUR_REDIRECT_URI"
- });
-
- localStorage.removeItem("code_verifier");
- localStorage.setItem("refresh_token", refresh_token);
- localStorage.setItem("access_token", access_token);
-};
+ error.response.headers.get("Date"); // You can access the response here
-const refreshHandler = () => {
- const refreshToken = localStorage.getItem("refresh_token");
- const { access_token, refresh_token } = authFlow.refresh(refreshToken);
+ console.error(error);
+ // SpotifyError: 401 Unauthorized (https://api.spotify.com/v1/me) : Invalid access token
+ return;
+ }
- localStorage.setItem("refresh_token", refresh_token);
- localStorage.setItem("access_token", access_token);
-};
+ // If it's not a SpotifyError, then it's some type of network error that fetch throws
+ // Or can be DOMException if you abort the request
+ console.error("We're totally f#%ked!");
+}
```
-Real code examples with PKCEAuthCode flow:
+### Rate Limiting 🕒
-- [examples/react-pkce-auth](https://github.com/MellKam/soundify/tree/main/examples/react-pkce-auth)
+If you're really annoying customer, Spotify may block you for some time. To know
+what time you need to wait, you can use `Retry-After` header, which will tell
+you time in seconds.
+[More about rate limiting↗](https://developer.spotify.com/documentation/web-api/concepts/rate-limits)
-
-
-
-This flow is used in server-to-server authentication. Since this flow does not
-include authorization, only endpoints that do not access user information can be
-accessed.
+To handle this automatically, you can use `waitForRateLimit` option in
+`SpotifyClient`. (it's disabled by default, because it may block your code for
+unknown time)
```ts
-import { ClientCredentials } from "@soundify/web-api";
-
-const authFlow = new ClientCredentials({
- client_id: "YOUR_CLIENT_ID",
- client_secret: "YOUR_CLIENT_SECRET"
+const client = new SpotifyClient("YOUR_ACCESS_TOKEN", {
+ waitForRateLimit: true,
+ // wait only if it's less than a minute
+ waitForRateLimit: (retryAfter) => retryAfter < 60,
});
-
-const { access_token } = await authFlow.getAccessToken();
```
-Real code examples with ClientCredentials flow:
-
-- [examples/deno-client-credentials](https://github.com/MellKam/soundify/tree/main/examples/deno-client-credentials)
+### Pagination
-
-
-Client Credentials flow
-
-This flow is used in server-to-server authentication. Since this flow does not
-include authorization, only endpoints that do not access user information can be
-accessed.
+To handle this automatically, you can use `waitForRateLimit` option in
+`SpotifyClient`. (it's disabled by default, because it may block your code for
+unknown time)
```ts
-import { ClientCredentials } from "@soundify/web-api";
-
-const authFlow = new ClientCredentials({
- client_id: "YOUR_CLIENT_ID",
- client_secret: "YOUR_CLIENT_SECRET"
+const client = new SpotifyClient("YOUR_ACCESS_TOKEN", {
+ waitForRateLimit: true,
+ // wait only if it's less than a minute
+ waitForRateLimit: (retryAfter) => retryAfter < 60,
});
-
-const { access_token } = await authFlow.getAccessToken();
```
-Real code examples with ClientCredentials flow:
-
-- [examples/deno-client-credentials](https://github.com/MellKam/soundify/tree/main/examples/deno-client-credentials)
+### Pagination
-
-
-
-The implicit grant flow is carried out on the client side and it does not
-involve secret keys. Access tokens issued are short-lived with no refresh token
-to extend them when they expire.
-
-> As from Spotify docs: "The implicit grant flow has some important security
-> flaws, thus **we don't recommend using this flow**. If you need to implement
-> authorization where storing your client secret is not possible, use
-> Authorization code with PKCE instead."
+To simplify the process of paginating through the results, we provide a
+`PageIterator` class.
```ts
-import { ImplicitGrant } from "@soundify/web-api";
-
-const authFlow = new ImplicitGrant("YOUR_CLIENT_ID");
-
-const authorize = () => {
- const state = crypto.randomUUID();
- localStorage.setItem("state", state);
+import { getPlaylistTracks, SpotifyClient } from "@soundify/web-api";
+import { PageIterator } from "@soundify/web-api/pagination";
- location.replace(
- authFlow.getAuthURL({
- scopes: ["user-read-email"],
- state,
- redirect_uri: "YOUR_REDIRECT_URI"
- })
- );
-};
+const client = new SpotifyClient("YOUR_ACCESS_TOKEN", {
+ waitForRateLimit: true,
+});
-const handleCallback = () => {
- const data = ImplicitGrant.parseCallbackData(location.hash);
- if ("error" in data) {
- throw new Error(data.error);
- }
+const playlistIter = new PageIterator(
+ (opts) => getPlaylistTracks(client, "37i9dQZEVXbMDoHDwVN2tF", opts),
+);
- const storedState = localStorage.getItem("state");
- if (!storedState || !params.state || storedState !== params.state) {
- throw new Error("Invalid state");
- }
+// iterate over all tracks in the playlist
+for await (const track of playlistIter) {
+ console.log(track);
+}
- localStorage.removeItem("state");
- localStorage.setItem("access_token", data.access_token);
-};
+// or collect all tracks into an array
+const allTracks = await playlistIter.collect();
+console.log(allTracks.length);
```
-Real code examples with ImplicitGrant flow:
-
-- [examples/react-implicit-grant](https://github.com/MellKam/soundify/tree/main/examples/react-implicit-grant)
+## Authorization
-
+Soundify doesn't provide any tools for authorization, because that would require
+to write whole oauth library in here. We have many other battle-tested oauth
+solutions, like [oauth4webapi](https://github.com/panva/oauth4webapi) or
+[oidc-client-ts](https://github.com/authts/oidc-client-ts). I just don't see a
+point in reinventing the wheel 🫤.
-## Auth provider and automatic tokens refreshing
+Despite this, we have a huge directory of examples, including those for
+authorization.
+[OAuth2 Examples↗](https://github.com/MellKam/soundify/tree/main/examples/oauth)
-As you saw earlier, you can simply pass the Access Token to SpotifyClient. But
-after some time (1 hour to be exact), it will expire and you'll need to deal
-with it yourself. Somehow get a new Access Token and set it on the client.
+### Token Refreshing
```ts
-import { SpotifyClient, AuthCode } from "@soundify/web-api";
-
-const authFlow = new AuthCode({ ... });
-const client = new SpotifyClient("ACCESS_TOKEN");
-// ...
-// Oops, token expires :(
+import { getCurrentUser, SpotifyClient } from "@soundify/web-api";
-const { access_token } = await authFlow.refresh("REFRESH_TOKEN");
-// set new token to your client
-client.setAuthProvider(access_token);
-```
+const refresher = () => {
+ // This function should return a new access token
+ // You can use any library you want to refresh the token
+ // Or even make it yourself, we don't care
+ return "YOUR_NEW_ACCESS";
+};
-But if you don't want to deal with all that, you can just create an
-`AuthProvider` and pass it instead of the Access Token. It will automatically
-refresh your token.
+const accessToken = await refresher();
+const client = new SpotifyClient(accessToken, { refresher });
-```ts
-import { SpotifyClient, AuthCode } from "@soundify/web-api";
+const me = await getCurrentUser(client);
+console.log(me);
-const authFlow = new AuthCode({ ... });
-const authProvider = authFlow.createAuthProvider("YOUR_REFRESH_TOKEN");
+// wait some time to expire the token ...
+// 2000 YEARS LATER 🧽
-const client = new SpotifyClient(authProvider);
+const me = await getCurrentUser(client);
+// client will receive 401 and call your refresher to get new token
+// you don't have to worry about it as long as your refresher is working
+console.log(me);
```
-You can create an `AuthProvider` from `AuthCode`, `PKCEAuthCode`,
-`ClientCredentials` flows. Implicit grant does not allow to implement such
-because you have to refresh the page to get a new token.
-
-Also you can create your own AuthProvider from `AuthProvider` class.
+## Other customizations
```ts
-import { AuthProvider } from "@soundify/web-api";
-
-const authProvider = new AuthProvider({
- refresher: async () => {
- // somehow refresh and get new `access_token`
- return { access_token };
- }
-});
-
-const client = new SpotifyClient(authProvider);
-```
-
-### Refresh Events
-
-AuthProvider provides an additional option for callback events that may be
-usefull in some cases.
+import { SpotifyClient } from "@soundify/web-api";
-```ts
-import { AuthProvider } from "@soundify/web-api";
-
-const authProvider = new AuthProvider({
- refresher: async () => {
- // ...
- },
- onRefreshSuccess: ({ access_token }) => {
- // do something with new token
- // for example, store it in localStorage
- localStorage.setItem("access_token", access_token);
- },
- onRefreshFailure: (error) => {
- // do something with error
- // for example, ask user to login again
- location.replace(PKCEAuthCode.getAuthURL({ ... }));
- },
+const client = new SpotifyClient("YOUR_ACCESS_TOKEN", {
+ // You can use any fetch implementation you want
+ // For example, you can use `node-fetch` in node.js
+ fetch: (input, init) => {
+ return fetch(input, init);
+ },
+ // You can change the base url of the client
+ // by default it's "https://api.spotify.com/"
+ beseUrl: "https://example.com/",
+ middlewares: [(next) => (url, opts) => {
+ // You can add your own middleware
+ // For example, you can add some headers to every request
+ return next(url, opts);
+ }],
});
```
-## Auth Scopes
-
-Scopes are usually used when creating authorization url. Pay attention to them,
-because many fields and endpoints may not be available if the correct scopes are
-not specified. Read the
-[Spotify guide](https://developer.spotify.com/documentation/general/guides/authorization/scopes/)
-to learn more.
-
-In Soundify scopes can be used as strings or with const object `SCOPES`.
-
-```ts
-import { SCOPES, AuthCode } from "@soundify/web-api";
-
-AuthCode.getAuthURL({
- scopes: ["user-read-email"],
- // or like this
- scopes: [SCOPES.USER_READ_EMAIL]
- // or use all scopes
- scopes: Object.values(SCOPES),
-})
-```
-
## Contributors ✨
-All contributions are very welcome ❤️ ([emoji key](https://allcontributors.org/docs/en/emoji-key))
+All contributions are very welcome ❤️
+([emoji key](https://allcontributors.org/docs/en/emoji-key))
diff --git a/codecov.yml b/codecov.yml
deleted file mode 100644
index 896ea35..0000000
--- a/codecov.yml
+++ /dev/null
@@ -1,6 +0,0 @@
-comment:
- layout: "reach, diff, flags, files"
- behavior: default
- require_changes: false
- require_base: no
- require_head: yes
diff --git a/deno.json b/deno.json
new file mode 100644
index 0000000..2f3e486
--- /dev/null
+++ b/deno.json
@@ -0,0 +1,10 @@
+{
+ "imports": {
+ "zod": "https://deno.land/x/zod@v3.22.4/mod.ts",
+ "oauth4webapi": "https://deno.land/x/oauth4webapi@v2.8.1/mod.ts",
+ "oak": "https://deno.land/x/oak@v12.5.0/mod.ts",
+ "std/": "https://deno.land/std@0.213.0/",
+ "@soundify/web-api": "./src/mod.ts"
+ },
+ "fmt": { "useTabs": true }
+}
diff --git a/deno.lock b/deno.lock
new file mode 100644
index 0000000..73f9625
--- /dev/null
+++ b/deno.lock
@@ -0,0 +1,151 @@
+{
+ "version": "3",
+ "remote": {
+ "https://deno.land/std@0.188.0/_util/asserts.ts": "178dfc49a464aee693a7e285567b3d0b555dc805ff490505a8aae34f9cfb1462",
+ "https://deno.land/std@0.188.0/_util/os.ts": "d932f56d41e4f6a6093d56044e29ce637f8dcc43c5a90af43504a889cf1775e3",
+ "https://deno.land/std@0.188.0/async/deferred.ts": "42790112f36a75a57db4a96d33974a936deb7b04d25c6084a9fa8a49f135def8",
+ "https://deno.land/std@0.188.0/bytes/bytes_list.ts": "31d664f4d42fa922066405d0e421c56da89d751886ee77bbe25a88bf0310c9d0",
+ "https://deno.land/std@0.188.0/bytes/concat.ts": "d26d6f3d7922e6d663dacfcd357563b7bf4a380ce5b9c2bbe0c8586662f25ce2",
+ "https://deno.land/std@0.188.0/bytes/copy.ts": "939d89e302a9761dcf1d9c937c7711174ed74c59eef40a1e4569a05c9de88219",
+ "https://deno.land/std@0.188.0/bytes/ends_with.ts": "4228811ebc71615d27f065c54b5e815ec1972538772b0f413c0efe05245b472e",
+ "https://deno.land/std@0.188.0/bytes/equals.ts": "b87494ce5442dc786db46f91378100028c402f83a14a2f7bbff6bda7810aefe3",
+ "https://deno.land/std@0.188.0/bytes/includes_needle.ts": "76a8163126fb2f8bf86fd7f22192c3bb04bf6a20b987a095127c2ca08adf3ba6",
+ "https://deno.land/std@0.188.0/bytes/index_of_needle.ts": "65c939607df609374c4415598fa4dad04a2f14c4d98cd15775216f0aaf597f24",
+ "https://deno.land/std@0.188.0/bytes/last_index_of_needle.ts": "7181072883cb4908c6ce8f7a5bb1d96787eef2c2ab3aa94fe4268ab326a53cbf",
+ "https://deno.land/std@0.188.0/bytes/mod.ts": "e869bba1e7a2e3a9cc6c2d55471888429a544e70a840c087672e656e7ba21815",
+ "https://deno.land/std@0.188.0/bytes/repeat.ts": "6f5e490d8d72bcbf8d84a6bb04690b9b3eb5822c5a11687bca73a2318a842294",
+ "https://deno.land/std@0.188.0/bytes/starts_with.ts": "3e607a70c9c09f5140b7a7f17a695221abcc7244d20af3eb47ccbb63f5885135",
+ "https://deno.land/std@0.188.0/crypto/keystack.ts": "877ab0f19eb7d37ad6495190d3c3e39f58e9c52e0b6a966f82fd6df67ca55f90",
+ "https://deno.land/std@0.188.0/crypto/timing_safe_equal.ts": "0fae34ee02264f309ae0b6e54e9746a7aba3996e5454903ed106967a7a9ef665",
+ "https://deno.land/std@0.188.0/encoding/base64.ts": "144ae6234c1fbe5b68666c711dc15b1e9ee2aef6d42b3b4345bf9a6c91d70d0d",
+ "https://deno.land/std@0.188.0/encoding/base64url.ts": "2ed4ba122b20fedf226c5d337cf22ee2024fa73a8f85d915d442af7e9ce1fae1",
+ "https://deno.land/std@0.188.0/http/_negotiation/common.ts": "14d1a52427ab258a4b7161cd80e1d8a207b7cc64b46e911780f57ead5f4323c6",
+ "https://deno.land/std@0.188.0/http/_negotiation/encoding.ts": "ff747d107277c88cb7a6a62a08eeb8d56dad91564cbcccb30694d5dc126dcc53",
+ "https://deno.land/std@0.188.0/http/_negotiation/language.ts": "7bcddd8db3330bdb7ce4fc00a213c5547c1968139864201efd67ef2d0d51887d",
+ "https://deno.land/std@0.188.0/http/_negotiation/media_type.ts": "58847517cd549384ad677c0fe89e0a4815be36fe7a303ea63cee5f6a1d7e1692",
+ "https://deno.land/std@0.188.0/http/cookie_map.ts": "d148a5eaf35f19905dd5104126fa47ac71105306dd42f129732365e43108b28a",
+ "https://deno.land/std@0.188.0/http/etag.ts": "6ad8abbbb1045aabf2307959a2c5565054a8bf01c9824ddee836b1ff22706a58",
+ "https://deno.land/std@0.188.0/http/http_errors.ts": "b9a18ef97d6c5966964de95e04d1f9f88a0f8bd8577c26fd402d9d632fb03a42",
+ "https://deno.land/std@0.188.0/http/http_status.ts": "8a7bcfe3ac025199ad804075385e57f63d055b2aed539d943ccc277616d6f932",
+ "https://deno.land/std@0.188.0/http/method.ts": "e66c2a015cb46c21ab0bb3589aa4fca43143a506cb324ffdfd42d2edef7bc0c4",
+ "https://deno.land/std@0.188.0/http/negotiation.ts": "46e74a6bad4b857333a58dc5b50fe8e5a4d5267e97292293ea65f980bd918086",
+ "https://deno.land/std@0.188.0/http/server_sent_event.ts": "f752c9e4f0eba247a3fead8bfe0883f44e04d31c2dcc88776ba5230b7165a460",
+ "https://deno.land/std@0.188.0/io/buf_reader.ts": "06fff3337091c49e99ebd2dd790c9a90364c087a2953ea081667400fd6c6cebb",
+ "https://deno.land/std@0.188.0/io/buf_writer.ts": "48c33c8f00b61dcbc7958706741cec8e59810bd307bc6a326cbd474fe8346dfd",
+ "https://deno.land/std@0.188.0/io/buffer.ts": "17f4410eaaa60a8a85733e8891349a619eadfbbe42e2f319283ce2b8f29723ab",
+ "https://deno.land/std@0.188.0/io/copy_n.ts": "0cc7ce07c75130f6fc18621ec1911c36e147eb9570664fee0ea12b1988167590",
+ "https://deno.land/std@0.188.0/io/limited_reader.ts": "6c9a216f8eef39c1ee2a6b37a29372c8fc63455b2eeb91f06d9646f8f759fc8b",
+ "https://deno.land/std@0.188.0/io/mod.ts": "2665bcccc1fd6e8627cca167c3e92aaecbd9897556b6f69e6d258070ef63fd9b",
+ "https://deno.land/std@0.188.0/io/multi_reader.ts": "9c2a0a31686c44b277e16da1d97b4686a986edcee48409b84be25eedbc39b271",
+ "https://deno.land/std@0.188.0/io/read_delim.ts": "c02b93cc546ae8caad8682ae270863e7ace6daec24c1eddd6faabc95a9d876a3",
+ "https://deno.land/std@0.188.0/io/read_int.ts": "7cb8bcdfaf1107586c3bacc583d11c64c060196cb070bb13ae8c2061404f911f",
+ "https://deno.land/std@0.188.0/io/read_lines.ts": "c526c12a20a9386dc910d500f9cdea43cba974e853397790bd146817a7eef8cc",
+ "https://deno.land/std@0.188.0/io/read_long.ts": "f0aaa420e3da1261c5d33c5e729f09922f3d9fa49f046258d4ff7a00d800c71e",
+ "https://deno.land/std@0.188.0/io/read_range.ts": "28152daf32e43dd9f7d41d8466852b0d18ad766cd5c4334c91fef6e1b3a74eb5",
+ "https://deno.land/std@0.188.0/io/read_short.ts": "805cb329574b850b84bf14a92c052c59b5977a492cd780c41df8ad40826c1a20",
+ "https://deno.land/std@0.188.0/io/read_string_delim.ts": "5dc9f53bdf78e7d4ee1e56b9b60352238ab236a71c3e3b2a713c3d78472a53ce",
+ "https://deno.land/std@0.188.0/io/slice_long_to_bytes.ts": "48d9bace92684e880e46aa4a2520fc3867f9d7ce212055f76ecc11b22f9644b7",
+ "https://deno.land/std@0.188.0/io/string_reader.ts": "da0f68251b3d5b5112485dfd4d1b1936135c9b4d921182a7edaf47f74c25cc8f",
+ "https://deno.land/std@0.188.0/io/string_writer.ts": "8a03c5858c24965a54c6538bed15f32a7c72f5704a12bda56f83a40e28e5433e",
+ "https://deno.land/std@0.188.0/media_types/_db.ts": "7606d83e31f23ce1a7968cbaee852810c2cf477903a095696cdc62eaab7ce570",
+ "https://deno.land/std@0.188.0/media_types/_util.ts": "916efbd30b6148a716f110e67a4db29d6949bf4048997b754415dd7e42c52378",
+ "https://deno.land/std@0.188.0/media_types/content_type.ts": "ad98a5aa2d95f5965b2796072284258710a25e520952376ed432b0937ce743bc",
+ "https://deno.land/std@0.188.0/media_types/extension.ts": "a7cd28c9417143387cdfed27d4e8607ebcf5b1ec27eb8473d5b000144689fe65",
+ "https://deno.land/std@0.188.0/media_types/extensions_by_type.ts": "43806d6a52a0d6d965ada9d20e60a982feb40bc7a82268178d94edb764694fed",
+ "https://deno.land/std@0.188.0/media_types/format_media_type.ts": "f5e1073c05526a6f5a516ac5c5587a1abd043bf1039c71cde1166aa4328c8baf",
+ "https://deno.land/std@0.188.0/media_types/get_charset.ts": "18b88274796fda5d353806bf409eb1d2ddb3f004eb4bd311662c4cdd8ac173db",
+ "https://deno.land/std@0.188.0/media_types/mod.ts": "d3f0b99f85053bc0b98ecc24eaa3546dfa09b856dc0bbaf60d8956d2cdd710c8",
+ "https://deno.land/std@0.188.0/media_types/parse_media_type.ts": "835c4112e1357e95b4f10d7cdea5ae1801967e444f48673ff8f1cb4d32af9920",
+ "https://deno.land/std@0.188.0/media_types/type_by_extension.ts": "daa801eb0f11cdf199445d0f1b656cf116d47dcf9e5b85cc1e6b4469f5ee0432",
+ "https://deno.land/std@0.188.0/media_types/vendor/mime-db.v1.52.0.ts": "6925bbcae81ca37241e3f55908d0505724358cda3384eaea707773b2c7e99586",
+ "https://deno.land/std@0.188.0/path/_constants.ts": "e49961f6f4f48039c0dfed3c3f93e963ca3d92791c9d478ac5b43183413136e0",
+ "https://deno.land/std@0.188.0/path/_interface.ts": "6471159dfbbc357e03882c2266d21ef9afdb1e4aa771b0545e90db58a0ba314b",
+ "https://deno.land/std@0.188.0/path/_util.ts": "d7abb1e0dea065f427b89156e28cdeb32b045870acdf865833ba808a73b576d0",
+ "https://deno.land/std@0.188.0/path/common.ts": "ee7505ab01fd22de3963b64e46cff31f40de34f9f8de1fff6a1bd2fe79380000",
+ "https://deno.land/std@0.188.0/path/glob.ts": "d479e0a695621c94d3fd7fe7abd4f9499caf32a8de13f25073451c6ef420a4e1",
+ "https://deno.land/std@0.188.0/path/mod.ts": "ee161baec5ded6510ee1d1fb6a75a0f5e4b41f3f3301c92c716ecbdf7dae910d",
+ "https://deno.land/std@0.188.0/path/posix.ts": "8b7c67ac338714b30c816079303d0285dd24af6b284f7ad63da5b27372a2c94d",
+ "https://deno.land/std@0.188.0/path/separator.ts": "0fb679739d0d1d7bf45b68dacfb4ec7563597a902edbaf3c59b50d5bcadd93b1",
+ "https://deno.land/std@0.188.0/path/win32.ts": "d186344e5583bcbf8b18af416d13d82b35a317116e6460a5a3953508c3de5bba",
+ "https://deno.land/std@0.188.0/streams/_common.ts": "f45cba84f0d813de3326466095539602364a9ba521f804cc758f7a475cda692d",
+ "https://deno.land/std@0.188.0/streams/buffer.ts": "d5b3d7d0299114e5b2ea895a8bf202a687fd915c5282f8096c7bae23b5a04407",
+ "https://deno.land/std@0.188.0/streams/byte_slice_stream.ts": "225d57263a34325d7c96cb3dafeb478eec0e6fd05cd0458d678752eadd132bb4",
+ "https://deno.land/std@0.188.0/streams/copy.ts": "75cbc795ff89291df22ddca5252de88b2e16d40c85d02840593386a8a1454f71",
+ "https://deno.land/std@0.188.0/streams/delimiter_stream.ts": "f69e849b3d1f59f02424497273f411105a6f76a9f13da92aeeb9a2d554236814",
+ "https://deno.land/std@0.188.0/streams/early_zip_readable_streams.ts": "4005fa74162b943f79899e5d7cb96adcbc0a6b867f9144974ed12d30e0a556e1",
+ "https://deno.land/std@0.188.0/streams/iterate_reader.ts": "bbec1d45c2df2c0c5920bad0549351446fdc8e0886d99e95959b259dbcdb6072",
+ "https://deno.land/std@0.188.0/streams/limited_bytes_transform_stream.ts": "05dc592ffaab83257494d22dd53917e56243c26e5e3129b3f13ddbbbc4785048",
+ "https://deno.land/std@0.188.0/streams/limited_transform_stream.ts": "d69ab790232c1b86f53621ad41ef03c235f2abb4b7a1cd51960ad6e12ee55e38",
+ "https://deno.land/std@0.188.0/streams/merge_readable_streams.ts": "5d6302888f4bb0616dafb5768771be0aec9bedc05fbae6b3d726d05ffbec5b15",
+ "https://deno.land/std@0.188.0/streams/mod.ts": "c07ec010e700b9ea887dc36ca08729828bc7912f711e4054e24d33fd46282252",
+ "https://deno.land/std@0.188.0/streams/read_all.ts": "ee319772fb0fd28302f97343cc48dfcf948f154fd0d755d8efe65814b70533be",
+ "https://deno.land/std@0.188.0/streams/readable_stream_from_iterable.ts": "cd4bb9e9bf6dbe84c213beb1f5085c326624421671473e410cfaecad15f01865",
+ "https://deno.land/std@0.188.0/streams/readable_stream_from_reader.ts": "bfc416c4576a30aac6b9af22c9dc292c20c6742141ee7c55b5e85460beb0c54e",
+ "https://deno.land/std@0.188.0/streams/reader_from_iterable.ts": "55f68110dce3f8f2c87b834d95f153bc904257fc65175f9f2abe78455cb8047c",
+ "https://deno.land/std@0.188.0/streams/reader_from_stream_reader.ts": "fa4971e5615a010e49492c5d1688ca1a4d17472a41e98b498ab89a64ebd7ac73",
+ "https://deno.land/std@0.188.0/streams/text_delimiter_stream.ts": "20e680ab8b751390e359288ce764f9c47d164af11a263870746eeca4bc7d976b",
+ "https://deno.land/std@0.188.0/streams/text_line_stream.ts": "0f2c4b33a5fdb2476f2e060974cba1347cefe99a4af33c28a57524b1a34750fa",
+ "https://deno.land/std@0.188.0/streams/to_transform_stream.ts": "7f55fc0b14cf3ed0f8d10d8f41d05bdc40726e44a65c37f58705d10a615f0159",
+ "https://deno.land/std@0.188.0/streams/writable_stream_from_writer.ts": "56fff5c82fb736fdd669b567cc0b2bbbe0351002cd13254eae26c366e2bed89a",
+ "https://deno.land/std@0.188.0/streams/write_all.ts": "aec90152978581ea62d56bb53a5cbf487e6a89c902f87c5969681ffbdf32b998",
+ "https://deno.land/std@0.188.0/streams/writer_from_stream_writer.ts": "07c7ee025151a190f37fc42cbb01ff93afc949119ebddc6e0d0df14df1bf6950",
+ "https://deno.land/std@0.188.0/streams/zip_readable_streams.ts": "a9d81aa451240f79230add674809dbee038d93aabe286e2d9671e66591fc86ca",
+ "https://deno.land/std@0.213.0/dotenv/mod.ts": "46cc7a78cf3f7ba533c8c9b90407a365f925be332ebdc867a1f502614e3d8523",
+ "https://deno.land/std@0.213.0/dotenv/parse.ts": "55d5d1a5ba76c1324e6dc2f2f7917f03c47e5da5c2c55af11fd0fe2d6a3d3a2e",
+ "https://deno.land/std@0.213.0/dotenv/stringify.ts": "0047ad7068289735d08964046aea267a750c141b494ca0e38831b89be6c020c2",
+ "https://deno.land/std@0.213.0/encoding/_util.ts": "beacef316c1255da9bc8e95afb1fa56ed69baef919c88dc06ae6cb7a6103d376",
+ "https://deno.land/std@0.213.0/encoding/base64.ts": "0ec6d6e6b68fc38f6396277e5184bcd47c1a9db0222fd0b563487eb67e352741",
+ "https://deno.land/std@0.213.0/encoding/base64url.ts": "b6e2d187e425e27227d6162e297c2f356dd8f23d4ddca21d0850e6871fe8ef37",
+ "https://deno.land/x/oak@v12.5.0/application.ts": "3028d3f6fa5ee743de013881550d054372c11d83c45099c2d794033786d27008",
+ "https://deno.land/x/oak@v12.5.0/body.ts": "1899761b97fc9d776f3710b2637fb047ba29b968609afc6c0e5219b1108e703c",
+ "https://deno.land/x/oak@v12.5.0/buf_reader.ts": "26640736541598dbd9f2b84a9d0595756afff03c9ca55b66eef1911f7798b56d",
+ "https://deno.land/x/oak@v12.5.0/content_disposition.ts": "8b8c3cb2fba7138cd5b7f82fc3b5ea39b33db924a824b28261659db7e164621e",
+ "https://deno.land/x/oak@v12.5.0/context.ts": "895a2d40186b89c28ba3947bf08a9335f1a11fc33133f760082536b74c53d1ca",
+ "https://deno.land/x/oak@v12.5.0/deps.ts": "047cba410eec1da9e1d4b46d634a13b4fcb4bc643bf9593e2755077d2a5e5187",
+ "https://deno.land/x/oak@v12.5.0/etag.ts": "32e47726b41698aefdd71faac5aaf2907c9bdd41ef18a7693863be4f8fee115d",
+ "https://deno.land/x/oak@v12.5.0/forwarded.ts": "e656f96a85574e2a6ee54dc35efc9f72d543c9ae0923760ef426ee7369eef01c",
+ "https://deno.land/x/oak@v12.5.0/headers.ts": "769fd042d34fbcd5667cbd745b5c65d335cc8430e822dbf1f87d65313cab4b47",
+ "https://deno.land/x/oak@v12.5.0/helpers.ts": "6b03c6a2be06ec775d54449e442a2bac234aa952948ca758356eab6dc87af618",
+ "https://deno.land/x/oak@v12.5.0/http_server_native.ts": "6232bed3d7bc17136d1a7f7685a6f8a79c943694463f71cf743eac58e75ec34c",
+ "https://deno.land/x/oak@v12.5.0/http_server_native_request.ts": "552b174b5e13e92de8897d5b6f716b1e5a53543115481d65a651a41e4ca29ec9",
+ "https://deno.land/x/oak@v12.5.0/isMediaType.ts": "62d638abcf837ece3a8f07a4b7ca59794135cb0d4b73194c7d5837efd4161005",
+ "https://deno.land/x/oak@v12.5.0/mediaTyper.ts": "042b853fc8e9c3f6c628dd389e03ef481552bf07242efc3f8a1af042102a6105",
+ "https://deno.land/x/oak@v12.5.0/middleware.ts": "c7f7a0424a6dd99a00e4b8d7d6e131efc0facc8dea781845d713b63df8ef1862",
+ "https://deno.land/x/oak@v12.5.0/middleware/proxy.ts": "6f2799cf60d926e7a8d13ff757a59d7f0f930407db7ee9b81e7c064138eb89ff",
+ "https://deno.land/x/oak@v12.5.0/mod.ts": "f6aa47ad1b6099470c9a884cccad9d3ac0fd242ba940896291ab76cd26cf554b",
+ "https://deno.land/x/oak@v12.5.0/multipart.ts": "1484e01b98f5135f2aa09f7d0ce1e7be39109bf9f045ac660e941619d04e3d29",
+ "https://deno.land/x/oak@v12.5.0/range.ts": "1ca15fc1ac21c650c34e6997a75af2af9d9d8eb6fe2d5d1dadeac3dfd4a9c152",
+ "https://deno.land/x/oak@v12.5.0/request.ts": "b7f4f5c138c3feacd318ed333e3d3c0b5d37555b131ce38a2a8bb28415aab8d1",
+ "https://deno.land/x/oak@v12.5.0/response.ts": "7172285e58947057f36d6536b52a9cdffbdb03616555fa8e94b87f469a105f8a",
+ "https://deno.land/x/oak@v12.5.0/router.ts": "0f53d6249f9e8f89f2522b2b810b9302d0f22593c184b16b24b03bf2b7d42ea1",
+ "https://deno.land/x/oak@v12.5.0/send.ts": "5ec49f106294593f468317a0c885da4f3274bf6d0fe9e16a7304391730b4f4fb",
+ "https://deno.land/x/oak@v12.5.0/structured_clone.ts": "c3888b14d1eec558345bfbf13d0993d59bd45aaa8588444e35dd558c3a921cd8",
+ "https://deno.land/x/oak@v12.5.0/testing.ts": "37d684d57bb8e5150fb5eb2677e66b04dcb422709cf2c5a74c1df94d52aa02e2",
+ "https://deno.land/x/oak@v12.5.0/util.ts": "0a3fdffb114859c2de84e1783efa3a544af4d2af8c6f08e0d25655de9d3e69bb",
+ "https://deno.land/x/oauth4webapi@v2.8.1/mod.ts": "cac8e55ad9db1ea74f90c1a39bfecee793dc4a02faba5f75a31ca64804ec5d68",
+ "https://deno.land/x/oauth4webapi@v2.8.1/src/index.ts": "bf667804a2faa04818067ff1f871bad6129c93c994395c10fd31bfc25c7bce11",
+ "https://deno.land/x/path_to_regexp@v6.2.1/index.ts": "894060567837bae8fc9c5cbd4d0a05e9024672083d5883b525c031eea940e556",
+ "https://deno.land/x/zod@v3.22.4/ZodError.ts": "4de18ff525e75a0315f2c12066b77b5c2ae18c7c15ef7df7e165d63536fdf2ea",
+ "https://deno.land/x/zod@v3.22.4/errors.ts": "5285922d2be9700cc0c70c95e4858952b07ae193aa0224be3cbd5cd5567eabef",
+ "https://deno.land/x/zod@v3.22.4/external.ts": "a6cfbd61e9e097d5f42f8a7ed6f92f93f51ff927d29c9fbaec04f03cbce130fe",
+ "https://deno.land/x/zod@v3.22.4/helpers/enumUtil.ts": "54efc393cc9860e687d8b81ff52e980def00fa67377ad0bf8b3104f8a5bf698c",
+ "https://deno.land/x/zod@v3.22.4/helpers/errorUtil.ts": "7a77328240be7b847af6de9189963bd9f79cab32bbc61502a9db4fe6683e2ea7",
+ "https://deno.land/x/zod@v3.22.4/helpers/parseUtil.ts": "f791e6e65a0340d85ad37d26cd7a3ba67126cd9957eac2b7163162155283abb1",
+ "https://deno.land/x/zod@v3.22.4/helpers/partialUtil.ts": "998c2fe79795257d4d1cf10361e74492f3b7d852f61057c7c08ac0a46488b7e7",
+ "https://deno.land/x/zod@v3.22.4/helpers/typeAliases.ts": "0fda31a063c6736fc3cf9090dd94865c811dfff4f3cb8707b932bf937c6f2c3e",
+ "https://deno.land/x/zod@v3.22.4/helpers/util.ts": "8baf19b19b2fca8424380367b90364b32503b6b71780269a6e3e67700bb02774",
+ "https://deno.land/x/zod@v3.22.4/index.ts": "d27aabd973613985574bc31f39e45cb5d856aa122ef094a9f38a463b8ef1a268",
+ "https://deno.land/x/zod@v3.22.4/locales/en.ts": "a7a25cd23563ccb5e0eed214d9b31846305ddbcdb9c5c8f508b108943366ab4c",
+ "https://deno.land/x/zod@v3.22.4/mod.ts": "64e55237cb4410e17d968cd08975566059f27638ebb0b86048031b987ba251c4",
+ "https://deno.land/x/zod@v3.22.4/types.ts": "724185522fafe43ee56a52333958764c8c8cd6ad4effa27b42651df873fc151e"
+ },
+ "workspace": {
+ "packageJson": {
+ "dependencies": [
+ "npm:all-contributors-cli@6.26.1",
+ "npm:tsup@8.0.1",
+ "npm:typescript@5.3.3"
+ ]
+ }
+ }
+}
diff --git a/examples/next-ssr/.env.example b/examples/next-ssr/.env.example
deleted file mode 100644
index a565b92..0000000
--- a/examples/next-ssr/.env.example
+++ /dev/null
@@ -1,3 +0,0 @@
-SPOTIFY_CLIENT_ID=
-SPOTIFY_CLIENT_SECRET=
-SPOTIFY_REDIRECT_URI=http://localhost:3000/api/callback
\ No newline at end of file
diff --git a/examples/next-ssr/.gitignore b/examples/next-ssr/.gitignore
deleted file mode 100644
index c87c9b3..0000000
--- a/examples/next-ssr/.gitignore
+++ /dev/null
@@ -1,36 +0,0 @@
-# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
-
-# dependencies
-/node_modules
-/.pnp
-.pnp.js
-
-# testing
-/coverage
-
-# next.js
-/.next/
-/out/
-
-# production
-/build
-
-# misc
-.DS_Store
-*.pem
-
-# debug
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-.pnpm-debug.log*
-
-# local env files
-.env*.local
-
-# vercel
-.vercel
-
-# typescript
-*.tsbuildinfo
-next-env.d.ts
diff --git a/examples/next-ssr/README.md b/examples/next-ssr/README.md
deleted file mode 100644
index f3f1c6e..0000000
--- a/examples/next-ssr/README.md
+++ /dev/null
@@ -1,5 +0,0 @@
-Implicit Grant flow
-
-The implicit grant flow is carried out on the client side and it does not
-involve secret keys. Access tokens issued are short-lived with no refresh token
-to extend them when they expire.
-
-> As from Spotify docs: "The implicit grant flow has some important security
-> flaws, thus **we don't recommend using this flow**. If you need to implement
-> authorization where storing your client secret is not possible, use
-> Authorization code with PKCE instead."
+To simplify the process of paginating through the results, we provide a
+`PageIterator` class.
```ts
-import { ImplicitGrant } from "@soundify/web-api";
-
-const authFlow = new ImplicitGrant("YOUR_CLIENT_ID");
-
-const authorize = () => {
- const state = crypto.randomUUID();
- localStorage.setItem("state", state);
+import { getPlaylistTracks, SpotifyClient } from "@soundify/web-api";
+import { PageIterator } from "@soundify/web-api/pagination";
- location.replace(
- authFlow.getAuthURL({
- scopes: ["user-read-email"],
- state,
- redirect_uri: "YOUR_REDIRECT_URI"
- })
- );
-};
+const client = new SpotifyClient("YOUR_ACCESS_TOKEN", {
+ waitForRateLimit: true,
+});
-const handleCallback = () => {
- const data = ImplicitGrant.parseCallbackData(location.hash);
- if ("error" in data) {
- throw new Error(data.error);
- }
+const playlistIter = new PageIterator(
+ (opts) => getPlaylistTracks(client, "37i9dQZEVXbMDoHDwVN2tF", opts),
+);
- const storedState = localStorage.getItem("state");
- if (!storedState || !params.state || storedState !== params.state) {
- throw new Error("Invalid state");
- }
+// iterate over all tracks in the playlist
+for await (const track of playlistIter) {
+ console.log(track);
+}
- localStorage.removeItem("state");
- localStorage.setItem("access_token", data.access_token);
-};
+// or collect all tracks into an array
+const allTracks = await playlistIter.collect();
+console.log(allTracks.length);
```
-Real code examples with ImplicitGrant flow:
-
-- [examples/react-implicit-grant](https://github.com/MellKam/soundify/tree/main/examples/react-implicit-grant)
+## Authorization
-
-
-# Soundify exapmle (next-ssr)
-
-// TODO
diff --git a/examples/next-ssr/next.config.js b/examples/next-ssr/next.config.js
deleted file mode 100644
index 6d32668..0000000
--- a/examples/next-ssr/next.config.js
+++ /dev/null
@@ -1,6 +0,0 @@
-/** @type {import('next').NextConfig} */
-const nextConfig = {
- reactStrictMode: true
-};
-
-module.exports = nextConfig;
diff --git a/examples/next-ssr/package.json b/examples/next-ssr/package.json
deleted file mode 100644
index f25eb26..0000000
--- a/examples/next-ssr/package.json
+++ /dev/null
@@ -1,23 +0,0 @@
-{
- "name": "@examples/next-ssr",
- "version": "0.1.0",
- "private": true,
- "scripts": {
- "dev": "next dev",
- "build": "next build",
- "start": "next start",
- "lint": "next lint"
- },
- "dependencies": {
- "@types/node": "latest",
- "@types/react": "latest",
- "@types/react-dom": "latest",
- "cookies-next": "2.1.2",
- "next": "13.4.6",
- "react": "18.2.0",
- "react-dom": "18.2.0",
- "@soundify/web-api": "workspace:*",
- "@tanstack/react-query": "4.29.14",
- "typescript": "5.1.3"
- }
-}
diff --git a/examples/next-ssr/pages/_app.tsx b/examples/next-ssr/pages/_app.tsx
deleted file mode 100644
index 645c5f0..0000000
--- a/examples/next-ssr/pages/_app.tsx
+++ /dev/null
@@ -1,12 +0,0 @@
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import type { AppProps } from "next/app";
-
-const queryClient = new QueryClient();
-
-export default function App({ Component, pageProps }: AppProps) {
- return (
-