# @feedfm/web-sdk

> The Feed Web SDK is the official SDK for consuming the Feed API to stream music.

Latest version **1.2.0** (published 2023-10-10) · ISC license · 0 weekly downloads

## Install

```sh
npm install @feedfm/web-sdk
pnpm add @feedfm/web-sdk
yarn add @feedfm/web-sdk
bun add @feedfm/web-sdk
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2023-10-10 |
| First published | 2023-10-03 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 464.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | scanningcrew, mbelyaev, joegar123, ericlambrecht, eca246, akrveen, mishugana, mslade |

## Links

- npm: https://www.npmjs.com/package/@feedfm/web-sdk
- npm.io page: https://npm.io/package/@feedfm/web-sdk

## Recent versions

- 1.2.0 (latest) — 2023-10-10
- 1.2.1-beta.44.4bbbb09c.0 (prerelease) — 2024-02-27
- 1.2.1-beta.43.0f5c87eb.0 — 2024-02-27
- 1.2.1-beta.42.2d5bb625.0 — 2024-02-21
- 1.2.1-beta.40.63b81ab6.0 — 2024-02-21
- 1.2.1-beta.39.8e696a86.0 — 2024-02-21
- 1.1.0 — 2023-10-03
- 1.0.0 — 2023-10-03

## README

# Introduction

The Feed Web SDK is the official SDK for consuming the Feed API to stream music.

# Installation

First, install it in your project.

```bash
npm install @feedfm/web-sdk --save
```

# Usage

## With a bundler

### Procedural-style rendering

Import the `sdk` singleton and use it to play music.

```typescript
import { sdk } from '@feedfm/web-sdk';

async beginPlayback() {
  const player = await sdk.connect( 'my-app-token', 'my-app-secret' );

  if ( player === null ) {
    throw new Error( 'Unable to connect.' );
  }

  const { defaultStations } = sdk.state;
  player.playStation( defaultStations[0] );
}

beginPlayback();
```

### State-based rendering

You can also use `sdk.observe(listener)` to register a callback that will be invoked every time the SDK state changes.
With this, you can write state-based rendering logic that pairs well with component frameworks like React.

```typescript
function useFeed(): SDKState {
  const [ feedState, setFeedState ] = useState<SDKState>( sdk.state );

  useEffect( () => {
    sdk.observe( setFeedState );
    return () => sdk.stopObserving( setFeedState );
  }, [] );

  return feedState;
}
```

## Without a bundler

You can embed our SDK directly into your HTML page.

```html
<script src="//path/to/node_modules/@feedfm/web-sdk/dist/web-entry.js"></script>
```

This will introduce the `FeedFM` global, which functions the same as `sdk` in the sample above.

# Playback

The general flow of playback, as shown above, is:

1. Connect with your credentials, using `sdk.connect( token, secret, options )`. Once connected, the SDK's state will include a `player` and `defaultStations`.
2. Begin playback of a station using `player.playStation( station )`.
3. Use `pause()`, `play()`, `skip()`, and `back()` on the `player` to control playback. Use `stop()` to end a stream.

Many browsers forbid playback prior to users interacting with the page. Attempting this will cause an exception. You can inspect the boolean `state.userHasInteracted` to determine whether the user has interacted with the page or not.

# State

The SDK has a single state object that is updated throughout playback. It updates often, as part of the state includes the current playback position.

You can consume the SDK state in multiple ways:

* `sdk.state` -- this provides procedural access to the current state of the SDK.
* `sdk.observe( (newState) => ... )` -- this allows you to listen to changes to the state.
* `sdk.observeChanegs( ( oldState, newState ) => ... )` -- this allows you to listen to changes, but receiving both the
  old and new state. Helpful when you want to detect changes in value.

---
_Source: https://npm.io/package/@feedfm/web-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._