https://github.com/guidefari/spotify-effect
https://github.com/guidefari/spotify-effect
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/guidefari/spotify-effect
- Owner: guidefari
- Created: 2023-06-20T20:07:07.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2026-04-02T16:22:44.000Z (3 months ago)
- Last Synced: 2026-04-02T18:39:16.100Z (3 months ago)
- Language: TypeScript
- Size: 492 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# spotify-effect
A TypeScript SDK for the Spotify Web API built with [Effect](https://effect.website/) — a functional, type-safe approach to handling async operations, errors, and observability.
## What is this?
This is an **isomorphic** (works in both Node.js and browser environments) Effect-based wrapper around the Spotify Web API, inspired by [spotify-web-api-ts](https://github.com/inferrinizzard/spotify-web-api). It provides:
- **Type-safe API calls** with full TypeScript support
- **Functional error handling** using Effect's composable error management
- **Built-in retries & batching** via Effect's request resolvers
- **OpenTelemetry tracing** for observability (optional, via `SPOTIFY_EFFECT_TRACE=1`)
- **PKCE OAuth flow** support for browser-based authentication
- **Comprehensive test coverage** with Vitest
## Packages
- **`@spotify-effect/core`** — Core SDK with API clients, auth flows, and shared helpers
- **`@spotify-effect/browser`** — Browser-focused package with PKCE/session helpers and `SpotifyBrowser`
- **`@spotify-effect/otel-node`** — Node OpenTelemetry integration
## Examples
- **`examples/basic`** — Node.js example with tracing
- **`examples/browser`** — Browser-based PKCE authentication flow
- **`examples/otel`** — Ready-to-run OpenTelemetry collector stack
## Quick Start
```typescript
import { makeSpotifyLayer, Tracks } from "@spotify-effect/core";
import { Effect } from "effect";
const program = Effect.gen(function* () {
const tracks = yield* Tracks;
const track = yield* tracks.getTrack("4iV5W9uYEdYUVa79Axb7Rh");
return track;
}).pipe(Effect.provide(makeSpotifyLayer({}, { accessToken: "your-access-token" })));
Effect.runPromise(program);
```
## Learning Resources
- [Intro To Effect, Part 1: What Is Effect?](https://ybogomolov.me/01-effect-intro)
- [Effect Introduction](https://github.com/antoine-coulon/effect-introduction)
- [Generic batching & retries examples](https://gist.github.com/mikearnaldi/4a13fe6f51b28ad0b07fd7bbe3f4c49a)
## Observability
Request and auth flows emit Effect tracing spans at shared boundaries. Enable local tracing with `SPOTIFY_EFFECT_TRACE=1`. See `docs/tracing/otel.md` for setup notes and `examples/otel/` for a ready-to-run collector stack.
## Additional Notes
See `docs/` for more detailed documentation.