- v1.1.5Latest
- v1.1.4
- v1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.0
- v1.0.0-rc11
- v1.0.0-rc10
- v1.0.0-rc9
- v1.0.0-rc8
- v1.0.0-rc7
- v1.0.0-rc6
- v1.0.0-rc5
- v1.0.0-rc4
- v1.0.0-rc3
- v1.0.0-rc2
- v0.1.4-beta.0
- v0.1.3-beta.1
- v0.1.3-beta.0
- v0.1.2-beta.0
- v0.1.1-beta.0
- v0.1.0-alpha.3
- v0.1.0-alpha.2
- v0.1.0-alpha.1
- v0.1.0-alpha.0
- v0.0.37
- v0.0.36
- v0.0.35
- v0.0.34
- v0.0.33
- v0.0.32
- v0.0.31
- v0.0.30
- v0.0.29
- v0.0.28
- v0.0.27
- v0.0.26
- v0.0.25
- v0.0.24
- v0.0.23
- v0.0.22
- v0.0.21
- v0.0.20
- v0.0.15
- v0.0.14
- v0.0.13
- v0.0.12
- v0.0.11
- v0.0.10
- v0.0.9
- list
- v0.0.8
- v0.0.7
- v0.0.3
- 0.0.2
- v0.0.6
- v0.0.5
- v0.0.4
Soundify (ALPHA)
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.
What makes this library special?
- Multiplatform: You can use it with Node.js, Deno on the server, or with client-side JavaScript.
- Comprehensive Spotify Auth support: It can handle all Spotify Auth flows and automatically refreshes access tokens.
- Modern: It leverages modern web APIs like native
fetch
,crypto
,URLSearchParams
and doesnāt require any external dependencies. - Lightweight and treeshakable: Itās designed to be as small as possible (exact size TBD).
- TypeScript first: Itās built with TypeScript and provides great support for it out of the box.
- Great docs: The library comes with extensive documentation and lots of examples to help you get started.
Installation
npm.js/soundify-web-api
NPMnpm i soundify-web-api
Unfortunately, the soundify
package on the NPM was already taken ;(
// For nodejs (server-side)
import { ... } from "soundify-web-api"
// For client-side javascript
import { ... } from "soundify-web-api/web"
deno.land/x/soundify
Deno// Import from denoland (recomended)
import { ... } from "https://deno.land/x/soundify/mod.ts"
// Import from github repo main branch
import { ... } from "https://raw.githubusercontent.com/MellKam/soundify/main/mod.ts";
Gettings started
Letās write āHello world!ā with soundify.
import { getCurrentUserProfile, SpotifyClient } from "soundify-web-api";
const client = new SpotifyClient("YOUR_ACCESS_TOKEN");
const user = await getCurrentUserProfile(client);
console.log(user);
If your Access Token is valid it will output something like this
{
"id": "31xofk5q7l22rvsbff7yiechyx6i",
"display_name": "Soundify",
"type": "user",
"uri": "spotify:user:31xofk5q7l22rvsbff7yiechyx6i",
// etc...
}
But how to get your Access Token?
If you just want to get a token quickly you can go to the Spotify Console. Then navigate to any endpoint and click on āGET TOKENā. You will be prompted to select scopes and then redirected to authentification. You will then have your token in the āOAuth Tokenā field.
Or you can try running one of our examples with a simple http server that will give you your token. With node examples/node-express-auth or with deno examples/deno-oak-auth
Authorization
If you have no experience with Spotify Auth you can read more about it in the Spotify Authorization Guide.
Flows
Authorization flows are organized into separate namespaces, with each namespace containing all the necessary functions and classes to implement a specific authorization flow. This allows for easy importing of a specific flow.
For instance, the following code imports different authorization flows:
// Importing the Authorization Code flow
import { AuthCode } from "soundify-web-api"
// Importing the Authorization Code flow with PKCE
import { PKCEAuthCode } from "soundify-web-api"
// Importing the Client Credentials flow
import { ClientCredentials } from "soundify-web-api"
// Importing the Implicit Grant flow
import { ImplicitGrant } from "soundify-web-api"
You can take a look at the examples to see how to use each authorization flow.
- Authorization Code flow - examples/node-express-auth, examples/next-ssr, examples/deno-oak-auth
- Authorization Code flow with PKCE - examples/react-pkce-auth
- Client Credentials flow - TBD
- Implicit Grant flow - examples/react-implicit-grant
AuthProvider
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.
import { SpotifyClient } from "soundify-web-api"
const client = new SpotifyClient("ACCESS_TOKEN")
// ...
// Oops, token expires :(
client.setAuthProvider("NEW_ACCESS_TOKEN")
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.
import { AuthCode, SpotifyClient } from "soundify-web-api";
const authProvider = new AuthCode.AuthProvider({
client_id: "YOUR_SPOTIFY_CLIENT_ID",
client_secret: "YOUR_SPOTIFY_CLIENT_SECRET",
refresh_token: "YOUR_REFRESH_TOKEN",
});
const client = new SpotifyClient(authProvider);
You can create an AuthProvider
from AuthCode
, PKCEAuthCode
, ClientCredentials
flows. Implicit grant does not allow you to implement such a thing.
Auth Scopes
You will use auth scopes when creating an authorization url using the getAuthURL
function. You can pass scopes just as raw strings. It will be easy becase you will have autofill for them :)
import { AuthCode } from "soundify-web-api";
AuthCode.getAuthURL({
scopes: ["user-read-email", ...],
...
})
Or you can use the AUTH_SCOPES
const object, which is used as an enum
import { AuthCode, AUTH_SCOPES } from "soundify-web-api";
AuthCode.getAuthURL({
scopes: [AUTH_SCOPES.USER_READ_EMAIL],
...
})
If you need to set all scopes, it may be much easier to use AUTH_SCOPES
and take all values from it.
import { AuthCode, AUTH_SCOPES } from "soundify-web-api";
AuthCode.getAuthURL({
scopes: Object.values(AUTH_SCOPES),
...
})
Be careful with scopes, because many fields and endpoints may not be available because the auth scope is not set.
All contributions are very welcome ā¤ļø