README

@datafire/britbox

Client library for Rocket Services

Installation and Usage

npm install --save @datafire/britbox

let britbox = require('@datafire/britbox').create({
  access_token: "",
  refresh_token: "",
  client_id: "",
  client_secret: "",
  redirect_uri: "",
  resetPasswordAuth: "",
  verifyEmailAuth: ""
});

.then(data => {
  console.log(data);
});

Description

An Orchestration Layer that takes ISL services and packages them in a more targeted way for front-end applications. This in turn makes client integration easier and reduces the complexity and size of front-end applications.

Rocket is also customisable - allowing UI engineers to ‘remix’ the existing back-end services into something that best suits the application they are developing.

Actions

oauthCallback

Exchange the code passed to your redirect URI for an access_token

britbox.oauthCallback({
  "code": ""
}, context)

Input

input object
- code required string

Output

output object
- access_token string
- refresh_token string
- token_type string
- scope string
- expiration string

oauthRefresh

Exchange a refresh_token for an access_token

britbox.oauthRefresh(null, context)

Input

This action has no parameters

Output

output object
- access_token string
- refresh_token string
- token_type string
- scope string
- expiration string

getAccount

Get the details of an account along with the profiles and entitlements under it.

britbox.getAccount({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output Account

updateAccount

Update the details of an account.

With the exception of the address, this supports partial updates, so you can send just the properties you wish to update.

When the address is provided any properties which are omitted from the address will be cleared.

britbox.updateAccount({
  "body": {}
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required AccountUpdateRequest

Output

Output schema unknown

getPaymentMethods

Get the available payment methods under an account.

britbox.getPaymentMethods({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output array
- items PaymentMethod

addPaymentMethod

Add a new payment method to an account.

britbox.addPaymentMethod({
  "body": {
    "token": "",
    "type": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required AddPaymentMethodRequest

Output

output PaymentMethod

removePaymentMethod

Remove a payment method from an account.

britbox.removePaymentMethod({
  "id": ""
}, context)

Input

input object
- id required string: The id of the payment method to remove.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

Output schema unknown

getPaymentMethod

Get a payment method under an account.

britbox.getPaymentMethod({
  "id": ""
}, context)

Input

input object
- id required string: The id of the payment method to get.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output PaymentMethod

getPurchases

Get a list of all purchases made under an account.

britbox.getPurchases({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output array
- items Purchase

makePurchase

Purchase a plan or item offer. The result of a successful transaction is a new entitlement.

britbox.makePurchase({
  "body": {}
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required PurchaseRequest

Output

output Entitlement

cancelSubscription

Cancel a plan subscription.

A cancelled subscription will continue to be valid until the subscription expiry date or next renewal date.

britbox.cancelSubscription({
  "id": ""
}, context)

Input

input object
- id required string: The identifier of the current active subscription membership of the account.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

Output schema unknown

updateSubscription

Renew a cancelled subscription or switch subscription to a different plan.

When renewing a cancelled subscription membership, hit this endpoint with the id of subscription to renew.

To switch plans provide the id of the current active subscription membership of the account, and in the query specify the id of the plan to switch to.

britbox.updateSubscription({
  "id": ""
}, context)

Input

input object
- id required string: The identifier of the current subscription membership
- planId string: The id of the plan to switch to if switching plans.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

Output schema unknown

getDevices

Get all devices registered under this account.

Also includes information around device registration and deregistration limits.

britbox.getDevices({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output AccountDevices

registerDevice

If a device with the same id already exists a 409 conflict will be returned.

britbox.registerDevice({
  "body": {
    "id": "",
    "name": "",
    "type": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required DeviceRegistrationRequest

Output

output Device

authorizeDevice

Authorize a device from a generated device authorization code.

This is the second step in the process of authorizing a device by pin code.

Firstly the device must request a generated authorization code via the /authorization/device/code endpoint.

This endpoint then authorizes the device associated with the code to sign in to a user account. Typically this endpoint will be called from a page presented in the web app under the account section.

Once authorized, the device will then be able to sign in to that account via the /authorization/device endpoint, without needing to provide the credentials of the user.

britbox.authorizeDevice({
  "body": {
    "code": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required DeviceAuthorizationCode

Output

Output schema unknown

deregisterDevice

Deregister a playback device from an account.

britbox.deregisterDevice({
  "id": ""
}, context)

Input

input object
- id required string: The unique identifier for the registered device e.g. serial number.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

Output schema unknown

getDevice

Get a registered device.

britbox.getDevice({
  "id": ""
}, context)

Input

input object
- id required string: The unique identifier for the registered device e.g. serial number.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output Device

renameDevice

Rename a device

britbox.renameDevice({
  "id": "",
  "name": ""
}, context)

Input

input object
- id required string: The unique identifier for this registered device e.g. serial number.
- name required string: The new name for the device.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

Output schema unknown

getEntitlements

Get all entitlements under the account.

This list is returned under the call to get account information so a call here is only required when wishing to refresh a local copy of entitlements.

britbox.getEntitlements({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output array
- items Entitlement

getItemMediaFiles

Get the video files associated with an item given maximum resolution, device type and one or more delivery types.

This endpoint accepts an Account Catalog token, however if when requesting playback files you receive an 403 status code with error code 1 then the file you're requesting is classification restricted. This means you should switch to target the /account/items/{id}/videos-guarded endpoint, passing it an Account Playback token. If not already obtained, this token can be requested via the /itv/pinauthorization endpoint with an account level pin.

For convenience you may also access free / public files through this endpoint instead of the /items/{id}/videos endpoint, when authenticated.

Returns an array of video file objects which each include a url to a video.

The first entry in the array contains what is predicted to be the best match. The remainder of the entries, if any, may contain resolutions below what was requests. For example if you request HD-720 the response may also contain SD entries.

If you specify multiple delivery types, then the response array will insert types in the order you specify them in the query. For example stream,progressive would return an array with 0 or more stream files followed by 0 or more progressive files.

If no files are found a 404 is returned.

britbox.getItemMediaFiles({
  "id": "",
  "delivery": [],
  "resolution": ""
}, context)

Input

input object
- id required string: The identifier of the item whose video files to load.
- delivery required array: The video delivery type you require.
- resolution required string (values: HD-4K, HD-1080, HD-720, SD, External): The maximum resolution the device to playback the media can present.
- formats array: The set of media file formats that the device supports, in the order of preference.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output array
- items MediaFile

getItemMediaFilesGuarded

Get the video files associated with an item given maximum resolution, device type and one or more delivery types.

This endpoint is identical to the /account/items/{id}/videos however it expects an Account Playback token. This token, and in association this endpoint, is specifically for use when playback files are classification restricted and require an account level pin to access them.

Returns an array of video file objects which each include a url to a video.

If no files are found a 404 is returned.

britbox.getItemMediaFilesGuarded({
  "id": "",
  "delivery": [],
  "resolution": ""
}, context)

Input

input object
- id required string: The identifier of the item whose video files to load.
- delivery required array: The video delivery type you require.
- resolution required string (values: HD-4K, HD-1080, HD-720, SD, External): The maximum resolution the device to playback the media can present.
- formats array: The set of media file formats that the device supports, in the order of preference.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output array
- items MediaFile

generateNonce

Generate a new account nonce.

A nonce may be required to help sign a response from a third party service which will be passed back to these services.

For example a Facebook single-sign-on request initiated by a client application may first get a nonce from here to include in the request. Facebook will then include the nonce in the auth token it issues. This token can be passed back to our services and the nonce checked for validity.

britbox.generateNonce({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output AccountNonce

changePassword

Change the password of an account.

The expected token scope is Settings.

britbox.changePassword({
  "body": {
    "password": "",
    "profileToken": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required ChangePasswordRequest

Output

Output schema unknown

changePin

Change the pin of an account.

britbox.changePin({
  "body": {
    "pin": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required ChangePinRequest

Output

Output schema unknown

getProfile

Get the details of the active profile, including watched, bookmarked and rated items.

britbox.getProfile({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output ProfileDetail

getBookmarks

Get the map of bookmarked item ids (itemId => creationDate) under the active profile.

britbox.getBookmarks({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output object

getBookmarkList

Returns the list of bookmarked items under the active profile.

britbox.getBookmarkList({}, context)

Input

input object
- page integer: The page of items to load. Starts from page 1.
- page_size integer: The number of items to return in a page.
- order string (values: asc, desc): The list sort order, either 'asc' or 'desc'.
- item_type string (values: movie, show, season, episode, program, link, trailer, channel, customAsset): The item type to filter by. Defaults to unspecified.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItemList

deleteItemBookmark

Unbookmark an item under the active profile.

britbox.deleteItemBookmark({
  "itemId": ""
}, context)

Input

input object
- itemId required string: The identifier of the bookmark to delete.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

Output schema unknown

getItemBookmark

Get the bookmark for an item under the active profile.

britbox.getItemBookmark({
  "itemId": ""
}, context)

Input

input object
- itemId required string: The id of the item to get the bookmark for.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output Bookmark

bookmarkItem

Bookmark an item under the active profile.

Creates one if it doesn't exist, overwrites one if it does.

britbox.bookmarkItem({
  "itemId": ""
}, context)

Input

input object
- itemId required string: The id of the item to bookmark.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output Bookmark

getContinueWatchingList

Returns a list of items which have been watched but not completed under the active profile.

Multiple episodes under the same show may be watched or in progress, however only a single item belonging to a particular show will be included in the returned list.

The next episode to continue watching for a particular show will be the most recent incompletely watched episode, or the next episode following the most recently completely watched episode. Based on the specified show_item_type type, either the next episode, the season of the next episode, or the show will be included in the list.

britbox.getContinueWatchingList({}, context)

Input

input object
- show_item_type string (values: episode, season, show): The item type to be returned for continue watching items belonging to a show.
- include array: Include one opr more ancestor/children for items belonging to a show. Extra items
- page integer: The page of items to load. Starts from page 1.
- page_size integer: The number of items to return in a page.
- max_rating string: The maximum rating (inclusive) of an item returned, e.g. 'auoflc-pg'.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItemList

getNextPlaybackItem

Returns the next item to play given a source item id.

For an unwatched show it returns the first episode available to the account.

For a watched show it returns the last incompletely watched episode by the profile, or the episode that immediately follows the last completely watched episode or nothing.

For an episode it always returns the immediately following episode, if available to the account, or nothing.

If the response does not contain a next property then no item was found.

britbox.getNextPlaybackItem({
  "itemId": ""
}, context)

Input

input object
- itemId required string: The identifier of the source item to base the next to watch item off.
- max_rating string: The maximum rating (inclusive) of an item returned, e.g. 'auoflc-pg'.
- expand string (values: parent, ancestors): If no value is specified no dependencies are expanded.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output NextPlaybackItem

getRatings

Get the map of rated item ids (itemId => rating out of 10) under the active profile.

britbox.getRatings({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output object

getRatingsList

Returns the list of rated items under the active profile.

britbox.getRatingsList({}, context)

Input

input object
- page integer: The page of items to load. Starts from page 1.
- page_size integer: The number of items to return in a page.
- order string (values: asc, desc): The list sort order, either 'asc' or 'desc'.
- order_by string (values: date-added, date-modified): What to order by.
- item_type string (values: movie, show, season, episode, program, link, trailer, channel, customAsset): The item type to filter by. Defaults to unspecified.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItemList

getItemRating

Get the rating info for an item under the active profile.

britbox.getItemRating({
  "itemId": ""
}, context)

Input

input object
- itemId required string: The id of the item to get the rating info for.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output UserRating

rateItem

Rate an item under the active profile.

Creates one if it doesn't exist, overwrites one if it does.

britbox.rateItem({
  "itemId": "",
  "rating": 0
}, context)

Input

input object
- itemId required string: The id of the item to rate.
- rating required integer: The item rating between 1 and 10 inclusive.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output UserRating

deleteWatched

Remove the watched status of items under the active profile. Passing in specific itemIds to the item_ids query parameter will cause only these items to be removed. If this list is missing all watched items will be removed

britbox.deleteWatched({}, context)

Input

input object
- item_ids array: List of itemIds to delete. Omit this parameter to delete all items
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

Output schema unknown

getWatched

Get the map of watched item ids (itemId => last playhead position) under the active profile.

britbox.getWatched({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output object

getWatchedList

Returns the list of watched items under the active profile.

britbox.getWatchedList({}, context)

Input

input object
- page integer: The page of items to load. Starts from page 1.
- page_size integer: The number of items to return in a page.
- completed boolean: Filter by whether an item has been fully watched (completed) or not.
- order string (values: asc, desc): The list sort order, either 'asc' or 'desc'.
- order_by string (values: date-added, date-modified): What to order by.
- item_type string (values: movie, show, season, episode, program, link, trailer, channel, customAsset): The item type to filter by. Defaults to unspecified.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItemList

getItemWatchedStatus

Get the watched status info for an item under the active profile.

britbox.getItemWatchedStatus({
  "itemId": ""
}, context)

Input

input object
- itemId required string: The id of the item to get the watched status for.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output Watched

setItemWatchedStatus

Record the watched playhead position of a video under the active profile.

Can be used later to resume a video from where it was last watched.

Creates one if it doesn't exist, overwrites one if it does.

britbox.setItemWatchedStatus({
  "itemId": "",
  "position": 0
}, context)

Input

input object
- itemId required string: The id of the item being watched.
- position required integer: The playhead position to record.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output Watched

createProfile

Create a new profile under the active account.

britbox.createProfile({
  "body": {
    "name": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required ProfileCreationRequest

Output

output ProfileDetail

deleteProfileWithId

Delete a profile with a specific id under the active account.

Note that you cannot delete the primary profile.

britbox.deleteProfileWithId({
  "id": ""
}, context)

Input

input object
- id required string: The identifier of the profile to delete.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

Output schema unknown

getProfileWithId

Get the summary of a profile with a specific id under the active account.

britbox.getProfileWithId({
  "id": ""
}, context)

Input

input object
- id required string: The identifier of the profile to return.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output ProfileSummary

updateProfileWithId

Update the summary of a profile with a specific id under the active account.

This supports partial updates so you can send just the properties you wish to update.

britbox.updateProfileWithId({
  "id": "",
  "body": {}
}, context)

Input

input object
- id required string: The identifier of the profile to update.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required ProfileUpdateRequest

Output

Output schema unknown

requestEmailVerification

Request that the email address tied to an account be verified.

This will send a verification email to the email address of the primary profile containing a link which, once clicked, completes the verification process via the /verify-email endpoint.

Note that when an account is created this email is sent automatically so there's no need to call this directly.

If the user doesn't click the link before it expires then this endpoint can be called to request a new verification email. In the future it may also be used if we add support for changing an account email address.

britbox.requestEmailVerification({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

Output schema unknown

signOut

When a user signs out of an application we need to clear some basic cookies we assigned them during token authorization.

britbox.signOut({}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

Output schema unknown

getAccountToken

Request one or more Account level authorization tokens each with a chosen scope.

Tokens are used to access restricted service endpoints. These restricted endpoints will require a specific token type (e.g Account) with a specific scope (e.g. Catalog) before access is granted.

For convenience, where a Profile level token with the same scope exists it will also be returned.

Authorization with pin is not supported on this endpoint anymore. Use /itv/pinauthorization endpoint instead.

britbox.getAccountToken({
  "body": {
    "email": "",
    "password": "",
    "scopes": []
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required AccountTokenRequest

Output

output array
- items AccessToken

getAccountTokenByCode

Get Catalog tokens for an account using a device authorization code. Where a Profile level token of Catalog scope exists it will also be returned.

This is the final step in the process of authorizing a device by pin code.

Firstly the device must request a generated authorization code via the /authorization/device/code endpoint.

The code is subsequently used to authorize the device to sign in to a given account via the /account/devices/authorization endpoint. Typically this will be from a page presented in the web app under the account section.

Once authorized, this endpoint will allow the device to sign in without needing to provide the credentials of the user.

britbox.getAccountTokenByCode({
  "body": {
    "id": "",
    "code": "",
    "scopes": []
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required AccountTokenByCodeRequest

Output

output array
- items AccessToken

generateDeviceAuthorizationCode

Get a generated device authorization code.

This is the first step in the process of authorizing a device by pin code. The device will make a request to this endpoint providing a unique identifier for the device such as a serial number. This endpoint will then return a generated code which is tied to the given device.

The code may subsequently be used to authorize the device to sign in to an account via the /account/devices/authorization endpoint. Typically this will be from a page presented in the web app under the account section.

Once authorized, the device will then be able to sign in to that account via the /authorization/device endpoint, without needing to provide the credentials of the user.

britbox.generateDeviceAuthorizationCode({
  "body": {
    "id": "",
    "name": "",
    "type": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required DeviceRegistrationRequest

Output

output DeviceAuthorizationCode

getProfileToken

Request one or more Profile level authorization tokens each with a chosen scope.

Tokens are used to access restricted service endpoints. These restriced endpoints will require a specific token type (e.g Profile) with a specific scope (e.g. Catalog) before access is granted.

britbox.getProfileToken({
  "body": {
    "profileId": "",
    "scopes": []
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required ProfileTokenRequest

Output

output array
- items AccessToken

refreshToken

Refresh an account or profile level authorization token which is marked as refreshable.

britbox.refreshToken({
  "body": {
    "token": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required TokenRefreshRequest

Output

output AccessToken

singleSignOn

Exchange a third party single-sign-on token for our own authorization tokens.

britbox.singleSignOn({
  "body": {
    "provider": "",
    "token": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required SingleSignOnRequest

Output

output array
- items AccessToken

getPlansBT

Returns all the plans available for BT flow including additional description data.

britbox.getPlansBT({}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.

Output

output BtPlans

assignToken

Assigns an UserToken to a profile on the ITV side. Currently throws an exception.

britbox.assignToken({
  "body": {
    "token": "",
    "profileToken": ""
  }
}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvAssignBtTokenRequest

Output

Output schema unknown

checkUserToken

Checks a provided token for BT eligible user.

britbox.checkUserToken({
  "id": ""
}, context)

Input

input object
- id required string: User token provided by BT.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

Output schema unknown

getSubscriptionData

Returns the details of subscription data for a user with specified id.

britbox.getSubscriptionData({
  "id": ""
}, context)

Input

input object
- id required string: The identifier of the user to load.

Output

output SubscriptionDetails

getAppConfig

Get the global configuration for an application. Should be called during app statup.

This includes things like device and playback rules, classifications, sitemap and subscriptions.

You have the option to select specific configuration objects using the 'include' parameter, or if unspecified, getting all configuration.

britbox.getAppConfig({}, context)

Input

input object
- include array: A comma delimited list of config objects to return.
- system string: Classification system to load in case include = classification.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output AppConfig

checkEeBtEligibility

Check whether or not a user is eligible for switching to Bt or EE offers.

britbox.checkEeBtEligibility({}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.

Output

output EeBtEligibility

assignMsisdn

Assigns a msisdn to a profile on ITV side.

britbox.assignMsisdn({
  "body": {
    "msisdn": "",
    "profileToken": "",
    "trackingHeader": "",
    "eeProductId": ""
  }
}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvAssignMsisdnRequest

Output

Output schema unknown

getEligibleOffers

Returns eligible partner specific offers for the querying partner for an EE MSISDN. This call is supposed to be called after we have MSISDN accired. This call should be followed by POST /ee/msisdn.

britbox.getEligibleOffers({
  "body": {
    "msisdn": "",
    "accessToken": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required EeOffersRequest

Output

output EeOffersResponse

validatePinRequest

Validate PIN request created by calling POST /ee/pin This call is to validate MSISDN entered by a user not comming through EE network. This call should be called after PUT /ee/pin. This call should be followed by POST /ee/offers.

britbox.validatePinRequest({
  "body": {
    "pinReference": "",
    "pin": "",
    "accessToken": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required EeValidatePinRequest

Output

output EeValidatePinResponse

createPinRequest

Creates a PIN request that will send an SMS to the given msisdn. This call is to validate MSISDN entered by a user not comming through EE network. This call should be followed by POST ee/pin.

britbox.createPinRequest({
  "body": {
    "msisdn": "",
    "accessToken": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required EeCreatePinRequest

Output

output EeCreatePinResponse

getPlansEE

Returns all the plans available for EE flow including additional description data.

britbox.getPlansEE({}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.

Output

output EePlans

getPlanEE

Returns the plan description for EE flow including additional description data.

britbox.getPlanEE({
  "id": ""
}, context)

Input

input object
- id required string: The identifier of the plan received from ee/offers.
- lang string: Language code for the preferred language to be returned in the response.

Output

output EePlanListItem

createToken

Returns a token for later calls to EE API. TTL is one hour. Recommended is FE refreshes this token before each call.

britbox.createToken(null, context)

Input

This action has no parameters

Output

output EeCreateTokenResponse

getItem

Returns the details of an item with the specified id.

britbox.getItem({
  "id": ""
}, context)

Input

input object
- id required string: The identifier of the item to load.
- max_rating string: The maximum rating (inclusive) of items returned, e.g. 'auoflc-pg'.
- expand string (values: all, children, ancestors, parent): If no value is specified no dependencies are expanded.
- select_season string (values: first, latest): Given a provided show id, it can be useful to get the details of a child season. This option
- use_custom_id boolean: Set to true when passing a custom Id as the id path parameter.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItemDetail

getItemChildrenList

Returns the List of child summary items under an item.

If the item is a Season then the children will be episodes and ordered by episode number.

If the item is a Show then the children will be Seasons and ordered by season number.

Returns 404 if no children found.

britbox.getItemChildrenList({
  "id": ""
}, context)

Input

input object
- id required string: The identifier of the item whose children to load.
- page integer: The page of items to load. Starts from page 1.
- page_size integer: The number of items to return in a page.
- max_rating string: The maximum rating (inclusive) of items returned, e.g. 'auoflc-pg'.
- order string (values: asc, desc): The list sort order, either 'asc' or 'desc'.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItemList

getItemRelatedList

Returns the list of items related to the parent item.

Note for now, due to the size of the list being unknown, only a single page will be returned.

britbox.getItemRelatedList({
  "id": ""
}, context)

Input

input object
- id required string: The identifier of the item to based related items off.
- page integer: The page of items to load. Starts from page 1.
- page_size integer: The number of items to return in a page.
- max_rating string: The maximum rating (inclusive) of items returned, e.g. 'auoflc-pg'.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItemList

getPublicItemMediaFiles

Get the free / public video files associated with an item given maximum resolution, device type and one or more delivery types.

Returns an array of video file objects which each include a url to a video.

If no files are found a 404 is returned.

britbox.getPublicItemMediaFiles({
  "id": "",
  "delivery": [],
  "resolution": ""
}, context)

Input

input object
- id required string: The identifier of the item whose video files to load.
- delivery required array: The video delivery type you require.
- resolution required string (values: HD-4K, HD-1080, HD-720, SD, External): The maximum resolution the device to playback the media can present.
- formats array: The set of media file formats that the device supports, in the order of preference.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output array
- items MediaFile

getAnonNextPlaybackItem

Identical to GET /account/profile/items/{itemId}/next route but for users that are not logged in i.e. this endpoint does not require authorisation

britbox.getAnonNextPlaybackItem({
  "itemId": ""
}, context)

Input

input object
- itemId required string: The identifier of the source item to base the next to watch item off.
- max_rating string: The maximum rating (inclusive) of an item returned, e.g. 'auoflc-pg'.
- expand string (values: parent, ancestors): If no value is specified no dependencies are expanded.
- device string: The type of device the content is targeting.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output NextPlaybackItem

getBillingHistory

Returns the list of billing records for specified payment platform.

britbox.getBillingHistory({
  "platform": "",
  "body": {
    "profileToken": ""
  }
}, context)

Input

input object
- platform required string: The identifier of the payment platform (stripe/itunes).
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvBillingHistoryRequest

Output

output ItvBillingHistory

getCardDetails

Get payment card details.

britbox.getCardDetails({
  "platform": "",
  "body": {
    "profileToken": ""
  }
}, context)

Input

input object
- platform required string: The identifier of the payment platform (stripe/itunes).
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvGetCardDetailsRequest

Output

output ItvCardDetails

changeCardDetails

Change payment card details.

britbox.changeCardDetails({
  "platform": "",
  "body": {
    "profileToken": "",
    "cardToken": ""
  }
}, context)

Input

input object
- platform required string: The identifier of the payment platform (stripe/itunes).
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvChangeCardDetailsRequest

Output

Output schema unknown

changeEmail

Change email address related to account/profile.

The expected token scope is Settings.

britbox.changeEmail({
  "body": {
    "email": "",
    "profileToken": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvChangeEmailRequest

Output

Output schema unknown

changeMarketing

Change marketing preferences related to account/profile.

The expected token scope is Settings.

britbox.changeMarketing({
  "body": {
    "emailOptIn": true,
    "profileToken": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvChangeMarketingRequest

Output

Output schema unknown

deleteAccount

Delete account in compliance with GDPR.

The expected token scope is Settings.

britbox.deleteAccount({
  "body": {
    "profileToken": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvDeleteAccountRequest

Output

Output schema unknown

getEntitlementsHistory

Returns the state of subscription for any payment platform.

britbox.getEntitlementsHistory({}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItvEntitlementsHistory

getFeatureFlag

Gets info whether or not a feature is enabled or disabled using a feature flag. Feature flags are set as a custom field within PM. It also supports custom feature flag data if needed. Such data can be return as well.

britbox.getFeatureFlag({
  "feature": ""
}, context)

Input

input object
- feature required string: The identifier of the feature to check for feature flag.
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItvFeatureFlag

getItemDownloadables

Returns the details of an item with the specified id.

britbox.getItemDownloadables({
  "body": {
    "ids": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required ItemDownloadableRequest

Output

output ItemDownloadableList

getItemItv

Redirects to corresponding Axis Item details page.

britbox.getItemItv({
  "externalId": ""
}, context)

Input

input object
- externalId required string: The external identifier of the item.

Output

output object

getItvPage

Returns a page with the specified id.

This is a cut down version for low memory devices.123

If targeting the search page you must url encode the search term as a parameter using the q key. For example if your browser path looks like /search?q=the then what you pass to this endpoint would look like /itv/page?path=/search%3Fq%3Dthe.

britbox.getItvPage({
  "path": ""
}, context)

Input

input object
- path required string: The path of the page to load, e.g. '/movies'.
- list_page_size integer: The number of items to load when prefetching and paging each list in the page row.
- list_page_size_large integer: The number of items to load when prefetching a continuous scroll list entry in a page.
- max_list_prefetch integer: The maximum number of lists to prefetch in the page.
- item_detail_expand string (values: all, children, ancestors): Only relevant when loading item detail pages as these embed a detailed item in the main page entry.
- item_detail_select_season string (values: first, latest): Only relevant when loading show detail pages as these embed a detailed item in the main page entry.
- text_entry_format string (values: markdown, html): Only relevant to page entries of type TextEntry.
- max_rating string: The maximum rating (inclusive) of items returned, e.g. 'auoflc-pg'.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output Page

getAccountTokenWithPin

Provides authorization with parental control pin.

Returns an array containing account token with Playback scope.

Requires access token with Catalog scope.

Pin must be a 4-digit string

britbox.getAccountTokenWithPin({
  "body": {
    "pin": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvPinAuthRequest

Output

output array
- items AccessToken

upgradePlan

Upgrades the plan for the current user.

britbox.upgradePlan({
  "platform": "",
  "body": {
    "planId": ""
  }
}, context)

Input

input object
- platform required string: The identifier of the payment platform (stripe/itunes). Only Stripe is supported
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvUpgradePlanRequest

Output

Output schema unknown

getPlansITV

Returns the plans available for specified payment platform.

britbox.getPlansITV({
  "platform": ""
}, context)

Input

input object
- platform required string: The identifier of the payment platform (stripe/itunes).
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItvPlans

getProfileItv

Returns the ITV profile object.

britbox.getProfileItv({}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.

Output

output object

updateProfile

Update ITV profile.

The expected token scope is Settings.

britbox.updateProfile({
  "body": {
    "profileToken": ""
  }
}, context)

Input

input object
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvUpdateProfileRequest

Output

Output schema unknown

getItvProfileToken

Returns the ITV profile token.

britbox.getItvProfileToken({
  "body": {
    "password": ""
  }
}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvProfileTokenRequest

Output

output ItvProfileToken

cancelSubscriptionItv

Cancel a plan subscription.

A cancelled subscription will continue to be valid until the subscription expiry date or next renewal date.

britbox.cancelSubscriptionItv({
  "platform": "",
  "body": {
    "profileToken": ""
  }
}, context)

Input

input object
- platform required string: The identifier of the payment platform (stripe/itunes).
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvCancelSubscriptionRequest

Output

Output schema unknown

getCurrentSubscription

Returns the details of current subscription for specified payment platform.

britbox.getCurrentSubscription({
  "platform": ""
}, context)

Input

input object
- platform required string: The identifier of the payment platform (stripe/itunes).
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItvCurrentSubscription

confirmPurchase

Confirms purchase and returns the details of purchased subscription for specified payment platform.

britbox.confirmPurchase({
  "platform": "",
  "body": {
    "planId": "",
    "profileToken": "",
    "cardToken": ""
  }
}, context)

Input

input object
- platform required string: The identifier of the payment platform (stripe/itunes).
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvPurchaseRequest

Output

output ItvPurchase

getSaveOffer

Checks the provided coupon id for a user. Only Stripe platform is currently supported.

britbox.getSaveOffer({}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItvGetDiscountResponse

activateSaveOffer

Activates the discount for a user. Only Stripe platform is currently supported.

britbox.activateSaveOffer({
  "body": ""
}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.
- body required string

Output

Output schema unknown

getSubscriptionState

Returns the state of subscription for any payment platform.

britbox.getSubscriptionState({}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItvSubscriptionState

getUpcomingInvoice

Returns an upcoming invoice

britbox.getUpcomingInvoice({}, context)

Input

input object
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItvGetDiscountResponse

checkVoucher

Validates the coupon/voucher for specified payment platform.

britbox.checkVoucher({
  "platform": "",
  "body": {
    "voucher": ""
  }
}, context)

Input

input object
- platform required string: The identifier of the payment platform (stripe/itunes).
- lang string: Language code for the preferred language to be returned in the response.
- body required ItvVoucherRequest

Output

output ItvVoucher

getLists

Returns an array of item lists with their first page of content resolved.

britbox.getLists({
  "ids": []
}, context)

Input

input object
- ids required array: A comma delimited list of item list identifiers.
- page_size integer: The number of items to return in a page.
- max_rating string: The maximum rating (inclusive) of items returned, e.g. 'auoflc-pg'.
- order string (values: asc, desc): The list sort order, either 'asc' or 'desc'.
- order_by string (values: a-z, release-year, date-added): What to order by.
- item_type string (values: movie, show, season, episode, program, link, trailer, channel, customAsset): The item type to filter by. Defaults to unspecified.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output array
- items ItemList

getList

Returns a list of items under the specified item list

britbox.getList({
  "id": ""
}, context)

Input

input object
- id required string: The identifier of the list to load.
- page integer: The page of items to load. Starts from page 1.
- page_size integer: The number of items to return in a page.
- max_rating string: The maximum rating (inclusive) of items returned, e.g. 'auoflc-pg'.
- order string (values: asc, desc): The list sort order, either 'asc' or 'desc'.
- order_by string (values: a-z, release-year, date-added): What to order by.
- param string: The list parameter in format 'key:value', e.g. 'genre:action'.
- item_type string (values: movie, show, season, episode, program, link, trailer, channel, customAsset): The item type to filter by. Defaults to unspecified.
- device string: The type of device the content is targeting.
- sub string: The active subscription code.
- segments array: The list of segments to filter the response by.
- ff array: The set of opt in feature flags which cause breaking changes to responses.
- lang string: Language code for the preferred language to be returned in the response.

Output

output ItemList

getPage

Returns a page with the specified id.

britbox.getPage({
  "path": ""
}, context)

Input

input object
- path required string: The path of the page to load, e.g. '/movies'.
- list_page_size integer: The number of items to load when prefetching and paging each list in th

Usage no npm install needed!

README

@datafire/britbox

Installation and Usage

Description

Actions

oauthCallback

Input

Output

oauthRefresh

Input

Output

getAccount

Input

Output

updateAccount

Input

Output

getPaymentMethods

Input

Output

addPaymentMethod

Input

Output

removePaymentMethod

Input

Output

getPaymentMethod

Input

Output

getPurchases

Input

Output

makePurchase

Input

Output

cancelSubscription

Input

Output

updateSubscription

Input

Output

getDevices

Input

Output

registerDevice

Input

Output

authorizeDevice

Input

Output

deregisterDevice

Input

Output

getDevice

Input

Output

renameDevice

Input

Output

getEntitlements

Input

Output

getItemMediaFiles

Input

Output

getItemMediaFilesGuarded

Input

Output

generateNonce

Input

Output

changePassword

Input

Output

changePin

Input

Output

getProfile

Input