API wrapper for Ustream, IBM's cloud video service
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
CONTRIBUTING.md
LICENSE Initial commit Aug 15, 2017
README.md
package-lock.json
package.json

README.md

Ustream JavaScript SDK

npm version

JavaScript wrapper for Ustream's REST API.

Installation

NPM

npm install ustream-sdk

Yarn

yarn add ustream-sdk

Basic Usage

All methods that access API resources, such as ustream.video.* or ustream.channel.* will return a Promise.

let Ustream = require('ustream-sdk')

// Set up instance using password authentication
let ustream = new Ustream({
    username: "...",
    password: "...",
    client_id: "...",
    client_secret: "...",
    type: "password"
})

ustream.video.get(videoId).then((video) => {
    // Use video
}).catch((err) => {
    // Handle error
})

Paging Results

Some methods return data that is divided into many pages. These methods will return an object with helper methods to allow for easy access to both your data and next pages.

// Get list of channels
ustream.channel.list().then((pageableResult) => {
    // Access the list of channels
    let channels = pageableResult.data
    
    // Check if result set has a next page
    if (pageableResult.hasNextPage()) {
        // Retrieve the next page of channels
        pageableResult.next().then((nextPageResults) => {
            // Use next page's results
        })
    }
}).catch((err) => {
    console.warn(err)
})
Method Returns Description
next() Promise<PageableResult> Retrieves the next page of results. Returns null if a next page does not exist.
data() array<Object> Returns the data for a given page.
hasNextPage() boolean If true, next() will return a new page of data. If false, no next page exists.

Authentication API

Client Credentials Flow

let ustream = new Ustream({
    type: 'password',
    username: '...'
    password: '...'
    client_id: '...'
    client_secret: '...'
})

Oauth Implicit Authentication Flow

let ustream = new Ustream({
  type: 'oauth_token',
  access_token: '...',
  token_type: 'bearer',
  expires_in: 86400
})

Oauth Authorization Code Authentication Flow

let ustream = new Ustream({
  type: 'oauth_code',
  client_id: '...',
  client_secret: '...',
  code: '...',
  redirect_uri: '...'
})

Oauth Demo App

View Demo

Changing Authentication Credentials Workflow

If you choose to change your authentication workflow or swap out credentials after initializing Ustream, you can utilize the setAuthCredentials method.

ustream.setAuthCredentials({
    type: "<new authentication workflow>",
    ...
})

Video API

Upload Video

ustream.video.upload(channelId, file, opts)
Parameter Type Description
channelId int ID of an existing channel.
file.originalname string Name of file.
file.stream ReadStream File stream.
opts.title string Title of video.
opts.description string Description of video.
opts.protect "public" "private" Default is "private". If set to true, video will be published upon end of upload.

Video Upload Status

ustream.video.getStatus(channelId, videoId)
Parameter Type Description
channelId int ID of an existing channel.
videoId int ID of an existing video.

List Videos

ustream.video.list(channelId, pageSize, page)

Promise returns a Pageable result. See "Paging Results" section for details.

Parameter Type Description
channelId int Id of a channel.
pageSize int (optional) Default: 100. The number of results to show per page.
page int (optional) Default: 1. The page to retrieve.

Get Video Details

ustream.video.get(videoId)
Parameter Type Description
videoId int ID of an existing video.

Delete Video

ustream.video.remove(videoId)
Parameter Type Description
videoId int ID of an existing video.

Channel API

Get Channel

ustream.channel.get(channelId, opts)
Parameter Type Description
channelId int ID of an existing channel.
opts.detail_level string Default is null. If set to "minimal", the result set is limited to id, title, picture, owner and locks data. If the channel is protected, only minimal data can be retrieved without valid access token.

Create Channel

ustream.channel.create(channelId, opts)
Parameter Type Description
channelId int ID of an existing channel.
opts.description string Description of channel.

Edit Channel

ustream.channel.edit(channelId, title, opts)
Parameter Type Description
channelId int ID of an existing channel.
title string Title of channel.
opts.description string Description of channel.
opts.tags string Comma delimited list of channel tags

Delete Channel

ustream.channel.remove(channelId)
Parameter Type Description
channelId int ID of an existing channel.

List Channels

ustream.channel.list(pageSize, page)

Promise returns a Pageable result. See "Paging Results" section for details.

Parameter Type Description
pageSize int (optional) Default: 100. The number of results to show per page.
page int (optional) Default: 1. The page to retrieve.

Check Password Protection Status

ustream.channel.getPasswordProtectionStatus(channelId)
Parameter Type Description
channelId int ID of an existing channel.

Enable Password Protection

ustream.channel.enablePasswordProtection(channelId, password)
Parameter Type Description
channelId int ID of an existing channel.
password string The password used to access the channel.

Disable Password Protection

ustream.channel.disablePasswordProtection(channelId)
Parameter Type Description
channelId int ID of an existing channel.

Get Embed Lock Status

ustream.channel.getEmbedLockStatus(channelId)
Parameter Type Description
channelId int ID of an existing channel.

Edit Embed Lock Status

ustream.channel.setEmbedLock(channelId, isEmbedLocked)
Parameter Type Description
channelId int ID of an existing channel.
isEmbedLocked boolean Default is false. True to enable restricted embed access. False to disable.

Get Whitelisted URLs

ustream.channel.getUrlWhiteList(channelId)
Parameter Type Description
channelId int ID of an existing channel.

Add URL to Whitelist

ustream.channel.addUrlToWhiteList(channelId, url)
Parameter Type Description
channelId int ID of an existing channel.
url string URL to whitelisted domain.

Remove URLs from Whitelist

The API currently does not support removing a single URL from the whitelist. All URLs must be removed, then added.

ustream.channel.emptyUrlWhiteList(channelId, url)
Parameter Type Description
channelId int ID of an existing channel.
url string URL to whitelisted domain.

Sharing Control

ustream.channel.setSharingControl(channelId, canShare)
Parameter Type Description
channelId int ID of an existing channel.
canShare boolean If true, users will be able to share a channel's content.

Change Branding Type

ustream.channel.setBrandingType(channelId, type)
Parameter Type Description
channelId int ID of an existing channel.
type string The branding type.

Todo

Since the release of this SDK, Ustream has added many new endpoints to their API. Support for these endpoints will be implemented in the upcoming weeks.

  • Authentication
    • Oauth implicit flow
    • Oauth authorization code flow
  • Device passwords
    • Get device passwords
    • Create device password
    • Delete device password
  • Playlists
    • List the user's playlists
    • Create a playlist
    • Playlist details
    • Modify a playlist
    • Delete a playlist
    • Playlist videos
    • Playlist video
    • Channel playlists
  • Video (new endpoints)
    • Download video
    • Video expiration
    • Video thumbnail
    • Video labels
    • Video caption
    • Video trim
    • Video copy
      • Check copy status
    • Video chapters
  • Channel (new endpoints)
    • List featured videos
    • Update featured videos
    • Get channel managers
  • Stream settings
    • Multi quality streaming
  • Custom metadata
    • List metadata fields
    • Create new metadata field
    • Delete metadata field
  • Ingest settings
    • Get ingest settings
  • Other
    • Improve test coverage

Testing

All tests are located in the /test directory. To execute the testing suite, or check for style guide violations, run the following command.

npm run test

Issues and Contributing

Have a feature request or bug report? Create an entry in the issue tracker, and include as much detail as possible. I usually reply within 12 hours.

Code contributions must adhere to the contribution guidelines.