# Spotify Emulator (service host)

Create an instance:
curl -s -X POST https://spotify.emulators.dev/_emulate/instances
# Hosted deployments create instances lazily when the returned URL is first used. The instance URL is a capability: anyone who has it can read and modify the instance, so save the returned URLs. Never store real secrets in an emulator.
# The server generates an unguessable name. An optional {"instance":"<prefix>"} body adds a readable prefix.

Then use the returned providerBaseUrl / controlBaseUrl. Example below uses a sample instance.
# Spotify Emulator

Stateful Spotify Web API emulator focused on client credentials OAuth and catalog APIs.

Provider base URL: https://spotify.your-instance.emulators.dev
Control base URL: https://spotify.your-instance.emulators.dev/_emulate

Supported surfaces:
- Client credentials token endpoint: supported at /api/token
- REST API: partial at /

Control endpoints:
- https://spotify.your-instance.emulators.dev/_emulate/manifest
- https://spotify.your-instance.emulators.dev/_emulate/coverage
- https://spotify.your-instance.emulators.dev/_emulate/connections
- https://spotify.your-instance.emulators.dev/_emulate/state
- https://spotify.your-instance.emulators.dev/_emulate/ledger
- https://spotify.your-instance.emulators.dev/_emulate/faults
- POST https://spotify.your-instance.emulators.dev/_emulate/credentials
- POST https://spotify.your-instance.emulators.dev/_emulate/seed
- POST https://spotify.your-instance.emulators.dev/_emulate/reset

Fault injection:
Arm a one-shot provider failure with a glob pathPattern, then inspect /ledger for faulted: true.
curl -s -X POST https://spotify.your-instance.emulators.dev/_emulate/faults \
  -H "content-type: application/json" \
  -d '{"match":{"method":"GET","pathPattern":"/v1/*"},"response":{"status":503,"body":{"error":"temporary"}}}'

Connect:

## spotify-web-api-node (TypeScript)
import SpotifyWebApi from "spotify-web-api-node";

const spotify = new SpotifyWebApi({
  clientId: "<client_id>",
  clientSecret: "<client_secret>",
});

// Route both the accounts (token) and API hosts at the emulator.
const base = "https://spotify.your-instance.emulators.dev";

// Client credentials grant against the emulator token endpoint.
const auth = Buffer.from("<client_id>:<client_secret>").toString("base64");
const res = await fetch(`${base}/api/token`, {
  method: "POST",
  headers: {
    authorization: `Basic ${auth}`,
    "content-type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({ grant_type: "client_credentials" }),
});
const { access_token } = await res.json();
spotify.setAccessToken(access_token);

const results = await fetch(`${base}/v1/search?q=daft&type=artist`, {
  headers: { authorization: `Bearer ${access_token}` },
}).then((r) => r.json());

## Spotify base URL (env)
SPOTIFY_BASE_URL=https://spotify.your-instance.emulators.dev
SPOTIFY_TOKEN_URL=https://spotify.your-instance.emulators.dev/api/token
SPOTIFY_CLIENT_ID=<client_id>
SPOTIFY_CLIENT_SECRET=<client_secret>

## curl (client credentials)
curl -s -X POST https://spotify.your-instance.emulators.dev/api/token \
  -u "<client_id>:<client_secret>" \
  -d grant_type=client_credentials

## curl (search)
curl -s "https://spotify.your-instance.emulators.dev/v1/search?q=daft&type=artist" -H "authorization: Bearer <token>"

## Base URL (env)
SPOTIFY_BASE_URL=https://spotify.your-instance.emulators.dev

## Create a credential
curl -s -X POST https://spotify.your-instance.emulators.dev/_emulate/credentials \
  -H "content-type: application/json" \
  -d '{"type":"oauth-client-credentials"}'

## Inspect requests
curl -s https://spotify.your-instance.emulators.dev/_emulate/ledger