- 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.
- 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.
- Comprehensive Spotify Auth support: It can handle all Spotify Auth flows and automatically refreshes access tokens.
- 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
First of all, you should already have a Spotify app created. If not, go and create one here https://developer.spotify.com/dashboard
Let’s write “Hello world!” with soundify.
// main.js
import { getCurrentUserProfile, SpotifyClient } from "soundify-web-api";
const client = new SpotifyClient("YOUR_ACCESS_TOKEN");
const user = await getCurrentUserProfile(client);
console.log(user);
// If access token is valid it will output something like this
/**
{
id: '31xofk5q7l22rvsbff7yiechyx6i',
display_name: 'Soundify',
type: 'user',
uri: 'spotify:user:31xofk5q7l22rvsbff7yiechyx6i'
...
}
*/
But how to get your Access Token?
If you’re new to Spotify, you can read more about it in the Spotify Authorization Guide.
Next, you can go to examples/node-express-auth or examples/deno-oak-auth and see the example http server code that will help you get your tokens.
Authorization
The flows are separated by namespaces. Each namespace has all the necessary functions and classes to implement a given authorization flow.
This is how you can import specific authorization flow.
// Authorization code flow
import { AuthCode } from "soundify-web-api"
// Authorization code flow with PKCE
import { PKCEAuthCode } from "soundify-web-api"
// Client credentials flow
import { ClientCredentials } from "soundify-web-api"
// Implicit grant flow
import { ImplicitGrant } from "soundify-web-api"
Flows have similar functions and classes. For example getAuthURL
, getGrantData
and AuthProvider
.
AuthProvider
For authorization, you can simply use an access token and independently set a new access token after its expiration
import { SpotifyClient } from "soundify-web-api"
const client = new SpotifyClient("ACCESS_TOKEN")
// token expires
client.setAuthProvider("NEW_ACCESS_TOKEN")
But if you need automatic refresh, you can create an AuthProvider.
import { AuthCode, SpotifyClient } from "soundify-web-api"
// For authorization code flow
const authProvider = new AuthCode.AuthProvider({
client_id: "SPOTIFY_CLIENT_ID",
client_secret: "SPOTIFY_CLIENT_SECRET",
refresh_token: "YOUR_REFRESH_TOKEN",
})
// For authorization code flow with PKCE
const authProvider = new PKCEAuthCode.AuthProvider({
client_id: "SPOTIFY_CLIENT_ID",
refresh_token: "YOUR_REFRESH_TOKEN",
})
// For client credentials flow
const authProvider = new ClientCredentials.AuthProvider({
client_id: "SPOTIFY_CLIENT_ID",
client_secret: "SPOTIFY_CLIENT_SECRET",
})
const client = new SpotifyClient(authProvider)
The Implicit Grant does not have an AuthProvider because it does not have the ability to refresh the token without reloading the page. Therefore, every time a token expires, you must redirect the user to get a new token
Auth Scopes
Scopes can be setted just as array of string
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
.
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 ❤️