@ttab/api-client

v2.10.0

Published

7 months ago

Browser-friendly TypeScript/JavaScript client for TT Nyhetsbyrån public APIs.

Downloads

188

0High
0Medium
0Low

jej

api client browser news content tt tt nyhetsbyrån

@ttab/api-client

Browser-friendly TypeScript client for TT Nyhetsbyrån public APIs. The client code (and this README file) has been automatically generated from the API definition located at https://api.tt.se/docs.

Version License Monthly downloads

Instructions for building the client are here.

Getting started

Prerequisites

To access the APIs you need to have a registered user account at TT Nyhetsbyrån.

The API uses OAuth2 token authentication. To be able to generate an OAuth2 token you will need a OAuth2 client registered with TT Nyhetsbyrån. If you don't have one, please contact [email protected].

Obtaining an OAuth2 token

The OAuth2 endpoints are documented here. In short, to obtain a token you call the https://tt.se/o/oauth2/token endpoint like this:

curl -XPOST -d username="<USERNAME>" \
  -d password="<PASSWORD>" \
  -d grant_type=password \
  -d scope="roles" \
  -d client_id="<CLIENT_ID>" \
  -d client_secret="<CLIENT_SECRET>" \
  https://tt.se/o/oauth2/token

You will get a JSON payload back. One of the properties is called access_token and contains the the OAuth2 token you need to connect to the API. To run the examples below it is handy to have this token exported as an environment variable:

export TOKEN="a.DV_8caPCk7CVQs_jr4_MpqZSxj4e25N3GbTEGXk2w4MUwzB..."

Searching

Searching the database for matching items is a common operation. You supply the mediaType (image, text, video, etc.) and an object with query parameters, and get a result object with an array of search hits.

This is a basic query, looking for panda pictures:

import { Api } from '@ttab/api-client'

let api = new Api({ token: process.env.TOKEN || '' })

api.content.search('image', { q: 'panda' }).then((res) => {
  res.hits.forEach((hit) => {
    console.log(hit.uri, hit.product)
  })
})

The search result is restricted to only match items allowed by the customer agreements linked to your user account. If you wish to further restrict the search result to match a given agreement you can use the agr parameter:

api.content.search('image', { q: 'panda', agr: [20031] }).then((res) => {
  res.hits.forEach((hit) => {
    console.log(hit.uri, hit.product)
  })
})

You can also restrict the search result to only contain items matching one or more product codes:

api.content
  .search('image', { q: 'panda', p: ['FOGNRE', 'FOGNREEJ'] })
  .then((res) => {
    res.hits.forEach((hit) => {
      console.log(hit.uri, hit.product)
    })
  })

Streaming data

While the api.content.search() method only returns items that are already present in the database, the notification stream endpoint provides a way to get a near real-time stream of new items as they are being indexed.

You first need to create a notification stream by calling api.content.addNotificationStream(), which accepts roughly the same arguments as api.content.search() with the exception of arguments that affect time ranges and result pagination. They don't make any sense while streaming data, as we will always return the latest items added.

Notification streams support streaming content using the _all media type, somethihg that the now-deprecated streaming method api.content.stream had problems with.

By calling api.content.getNotificationStream(), with the ID of the newly created stream you will receive new items matching the search criteria as they are being indexed into the database. This is a HTTP long-poll call, which will hang until one or more items are available or the timeout (specified with the wait paramter; default 60s) is reached, whichever comes first.

Note that the state of the stream is kept server-side, so repeated calls to fetch items from the stream will yield different results.

Notification streams expire after 5 minutes of client inactivity. Calling api.content.getNotificationStream on an expired stream will yield HTTP 404.

This is a an simplified example streaming all text items. For production use you would probably want some better error handling logic.

import { Api } from '@ttab/api-client'

let api = new Api({ token: process.env.TOKEN || '' })

api.content
  .addNotificationStream('text', {})
  .then((stream) => {
    function loop() {
      return api.content
        .getNotificationStream('text', stream.id, {})
        .then((result) => {
          result.hits.forEach((hit) => {
            console.log(hit.uri, hit.source, hit.headline)
          })
          return loop()
        })
    }
    loop()
  })
  .catch((err) => {
    console.error(err)
  })

The ContentStream class

While you can handle stream loops yourself, the API client supplies a utility class to make content streaming easier.

Methods

constructor(api, mediaType, parameters) -
- api - an Api instance
- mediaType and parameters - the same arguments accepted by api.content.stream()
stop() - request that the content stream be stopped. When the stream has closed down and no more data events can be expected a final close event will be emitted.

Events

data - emitted once for every hit.
error - emitted on error. It is up to the user to decide how to handle this error and if/when to close the content stream.
close - emitted when the content stream is closed. No more data events will be emitted.

Error handling

On errors which the client is unlikely to recover from by itself (i.e. HTTP 4XX), the stream will automatically emit a close event and stop.

When encountering other errors (HTTP 5xx, connections errors, etc.) the stream uses an exponential backoff algorithm to determine an appropriate delay before retrying the request. The initial delay is 50ms and doubles after each consecutive error, up to 30s. The delay is reset to zero when a request completes successfully.

Example

The following code is equivalent to the loop in the previous section. It prints the uri, source and headline for each new image as it is added to the database. It handles errors by printing a stack trace and closing down the stream.

import { Api, ContentStream } from '@ttab/api-client'

let api = new Api({ token: process.env.TOKEN || '' })
let stream = new ContentStream(api, 'image', {})

stream.on('data', (hit) => {
  console.info(hit.uri, hit.source, hit.headline)
})

stream.on('error', (err) => {
  console.error('err', err)
})

stream.on('close', () => {
  console.info('closed')
})

Errors

Errors reported by the API or caused by the HTTP connection have the type ApiError.

API Reference

ContentV1

search(mediaType, parameters)

Searching the TT archives.

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" | "stockfoto" - Only return items of this media type.
parameters:
- q?: string - A query string used for free text searching.
- p?: Array<string> - A list of product codes. Only items matching at least one of these codes will be returned. The list of current product codes is here. Individual product codes may be prefixed with a '-' sign, indicating that the code should instead be excluded from the search result.
- agr?: Array<number> - A list of customer agreement IDs belonging to the current user. Only items covered by at least one of there agreements will be returned.
- tr?: "h" | "d" | "w" | "m" | "y" - Time range: last hour, day, week, month, or year.
- trs?: string - Start date
- tre?: string - End date
- pubstatus?: Array<"usable" | "replaced"> -
- s?: number - Size of search result.
- fr?: number - Index into the search result. Used for pagination. It is recommended to make this value a multiple of the search result size (s), as some media types do not support arbitrary values here.
- sort?: "default:desc" | "default:asc" | "date:desc" | "date:asc" | "versioncreated:desc" | "versioncreated:asc" | "versionstored:desc" | "versionstored:asc" | "relevance" - Sort order for the result. Documentation on various date fields can be found here.
  - default:desc / default:asc - Sort on the internal field '_tstamp' in descending or ascending order respectively.
  - date:desc / date:asc - Sort on the field 'date' in descending or ascending order respectively.
  - versioncreated:desc / versioncreated:asc - Sort on the field 'versioncreated' in descending or ascending order respectively.
  - versionstored:desc / versionstored:asc - Sort on the field 'versionstored' in descending or ascending order respectively.
  - relevance - Sort on relevance. The most relevant matches first.
- facets?: Array<"copyrightholder" | "person.name" | "place.name" | "product.code" | "subject.code"> - Enable search facets; in addition to the regular search result the API will also return one or more additional facets which contain information about how many search results can be expected if the current query is narrowed down using popular subject codes, product codes, etc.
- layout?: "bare" | "full" - By default the full TTNinjs document is returned for each search hit. This may be too cumbersome for some use cases; for example when the client requests a large search result to be displayed in a list form. This parameter allows the client to control the layout of the items in the search result:
  - full - (default) return the full TTNinjs document
  - bare - return only headline, date, uri, renditions, associations, pubstatus, originaltransmissionreference, copyrightholder. In addition, all associations except the first are stripped away, and renditions will only contain the thumbnail rendition.

Returns

Promise<{ 'hits': Array<ttninjs>; 'total': number; 'facets'?: { 'subject.code'?: Array<facet>; 'product.code'?: Array<facet>; 'place.name'?: Array<facet>; 'person.name'?: Array<facet>; 'copyrightholder'?: Array<facet>;};}>

Example

api.content
  .search('image', {
    q: 'panda',
    p: ['FOGNRE', '-FOGNREEJ'],
    agr: [20031, 20035],
    tr: 'w',
    sort: 'date:asc',
  })
  .then((result) => {
    // do something with result
  })

stream(mediaType, parameters)

Realtime delivery of content.

Long poll call that will wait for a specified time period (default: 60s, max 300s) until a matching item is published. The parameters are similar to those for search, with the exception that time ranges and pagination doesn't make sense in this context (we will always return the most recent item). DEPRECATED: This endpoint cannot guarantee delivery in the event that two items are published at the exact same time. Consider using /content/v1/{mediaType}/notification/stream instead.

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.
parameters:
- q?: string - A query string used for free text searching.
- p?: Array<string> - A list of product codes. Only items matching at least one of these codes will be returned. The list of current product codes is here. Individual product codes may be prefixed with a '-' sign, indicating that the code should instead be excluded from the search result.
- agr?: Array<number> - A list of customer agreement IDs belonging to the current user. Only items covered by at least one of there agreements will be returned.
- sort?: "default:desc" | "default:asc" | "date:desc" | "date:asc" | "versioncreated:desc" | "versioncreated:asc" | "versionstored:desc" | "versionstored:asc" | "relevance" - Sort order for the result. Documentation on various date fields can be found here.
  - default:desc / default:asc - Sort on the internal field '_tstamp' in descending or ascending order respectively.
  - date:desc / date:asc - Sort on the field 'date' in descending or ascending order respectively.
  - versioncreated:desc / versioncreated:asc - Sort on the field 'versioncreated' in descending or ascending order respectively.
  - versionstored:desc / versionstored:asc - Sort on the field 'versionstored' in descending or ascending order respectively.
  - relevance - Sort on relevance. The most relevant matches first.
- layout?: "bare" | "full" - By default the full TTNinjs document is returned for each search hit. This may be too cumbersome for some use cases; for example when the client requests a large search result to be displayed in a list form. This parameter allows the client to control the layout of the items in the search result:
  - full - (default) return the full TTNinjs document
  - bare - return only headline, date, uri, renditions, associations, pubstatus, originaltransmissionreference, copyrightholder. In addition, all associations except the first are stripped away, and renditions will only contain the thumbnail rendition.
- last?: string - The uri of the last item received.
- wait?: number - The time (in seconds) to wait for updates before returning an empty result.

Returns

Promise<{ 'hits': Array<ttninjs>;}>

Example

api.content
  .stream('image', {
    q: 'panda',
    p: ['FOGNRE', '-FOGNREEJ'],
    agr: [20031, 20035],
    sort: 'date:asc',
  })
  .then((result) => {
    // do something with result
  })

getNotifications(mediaType)

List all notifications

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.

Returns

Promise<Array<notification>>

Example

api.content.getNotifications('image').then((result) => {
  // do something with result
})

addNotificationMobile(mediaType, parameters)

Create a new mobile notification

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.
parameters:
- q?: string - A query string used for free text searching.
- p?: Array<string> - A list of product codes. Only items matching at least one of these codes will be returned. The list of current product codes is here. Individual product codes may be prefixed with a '-' sign, indicating that the code should instead be excluded from the search result.
- agr?: Array<number> - A list of customer agreement IDs belonging to the current user. Only items covered by at least one of there agreements will be returned.
- title: string -

Returns

Promise<notification>

Example

api.content
  .addNotificationMobile('image', {
    q: 'panda',
    p: ['FOGNRE', '-FOGNREEJ'],
    agr: [20031, 20035],
    title: 'my mobile notification',
  })
  .then((result) => {
    // do something with result
  })

addNotificationEmail(mediaType, parameters)

Create a new email notification

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.
parameters:
- q?: string - A query string used for free text searching.
- p?: Array<string> - A list of product codes. Only items matching at least one of these codes will be returned. The list of current product codes is here. Individual product codes may be prefixed with a '-' sign, indicating that the code should instead be excluded from the search result.
- agr?: Array<number> - A list of customer agreement IDs belonging to the current user. Only items covered by at least one of there agreements will be returned.
- title: string -
- email: string - The email address to send emails to.

Returns

Promise<notification>

Example

api.content
  .addNotificationEmail('image', {
    q: 'panda',
    p: ['FOGNRE', '-FOGNREEJ'],
    agr: [20031, 20035],
    title: 'my email notification',
    email: '[email protected]',
  })
  .then((result) => {
    // do something with result
  })

addNotificationScheduledEmail(mediaType, parameters)

Create a new scheduled email notification

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.
parameters:
- q?: string - A query string used for free text searching.
- p?: Array<string> - A list of product codes. Only items matching at least one of these codes will be returned. The list of current product codes is here. Individual product codes may be prefixed with a '-' sign, indicating that the code should instead be excluded from the search result.
- agr?: Array<number> - A list of customer agreement IDs belonging to the current user. Only items covered by at least one of there agreements will be returned.
- tr?: "h" | "d" | "w" | "m" | "y" - Time range: last hour, day, week, month, or year.
- title: string -
- email: string - The email address to send emails to.
- schedule: string - A cron expression.
- timezone?: string - A valid time zone name

Returns

Promise<notification>

Example

api.content
  .addNotificationScheduledEmail('image', {
    q: 'panda',
    p: ['FOGNRE', '-FOGNREEJ'],
    agr: [20031, 20035],
    tr: 'w',
    title: 'my scheduled email notification',
    email: '[email protected]',
    schedule: '0 0 12 * * MON-FRI',
    timezone: 'Europe/Stockholm',
  })
  .then((result) => {
    // do something with result
  })

addNotificationStream(mediaType, parameters)

Create a new content stream

Creates a new notification of type stream and returns the details. Items of the given mediaType matching the parameters q, p and agr will be added to the stream in near real-time as they are indexed into the content database. The contents of the stream can be consumed by calling the GET /content/v1/{mediaType}/notification/{id}/stream endpoint.

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.
parameters:
- q?: string - A query string used for free text searching.
- p?: Array<string> - A list of product codes. Only items matching at least one of these codes will be returned. The list of current product codes is here. Individual product codes may be prefixed with a '-' sign, indicating that the code should instead be excluded from the search result.
- agr?: Array<number> - A list of customer agreement IDs belonging to the current user. Only items covered by at least one of there agreements will be returned.
- title?: string -

Returns

Promise<notification>

Example

api.content
  .addNotificationStream('image', {
    q: 'panda',
    p: ['FOGNRE', '-FOGNREEJ'],
    agr: [20031, 20035],
    title: 'my stream notification',
  })
  .then((result) => {
    // do something with result
  })

updateNotificationMobile(mediaType, id, parameters)

Update an existing mobile notification

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.
id: string - An notification UUID string.
parameters:
- q?: string - A query string used for free text searching.
- p?: Array<string> - A list of product codes. Only items matching at least one of these codes will be returned. The list of current product codes is here. Individual product codes may be prefixed with a '-' sign, indicating that the code should instead be excluded from the search result.
- agr?: Array<number> - A list of customer agreement IDs belonging to the current user. Only items covered by at least one of there agreements will be returned.
- title: string -

Returns

Promise<notification>

Example

api.content
  .updateNotificationMobile('image', '4a37869c-808f-496f-b549-3da0821ce187', {
    q: 'panda',
    p: ['FOGNRE', '-FOGNREEJ'],
    agr: [20031, 20035],
    title: 'my mobile notification',
  })
  .then((result) => {
    // do something with result
  })

updateNotificationEmail(mediaType, id, parameters)

Update an existing email notification

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.
id: string - An notification UUID string.
parameters:
- q?: string - A query string used for free text searching.
- p?: Array<string> - A list of product codes. Only items matching at least one of these codes will be returned. The list of current product codes is here. Individual product codes may be prefixed with a '-' sign, indicating that the code should instead be excluded from the search result.
- agr?: Array<number> - A list of customer agreement IDs belonging to the current user. Only items covered by at least one of there agreements will be returned.
- title: string -
- email: string - The email address to send emails to.

Returns

Promise<notification>

Example

api.content
  .updateNotificationEmail('image', '4a37869c-808f-496f-b549-3da0821ce187', {
    q: 'panda',
    p: ['FOGNRE', '-FOGNREEJ'],
    agr: [20031, 20035],
    title: 'my email notification',
    email: '[email protected]',
  })
  .then((result) => {
    // do something with result
  })

updateNotificationScheduledEmail(mediaType, id, parameters)

Update an existing scheduled email notification

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.
id: string - An notification UUID string.
parameters:
- q?: string - A query string used for free text searching.
- p?: Array<string> - A list of product codes. Only items matching at least one of these codes will be returned. The list of current product codes is here. Individual product codes may be prefixed with a '-' sign, indicating that the code should instead be excluded from the search result.
- agr?: Array<number> - A list of customer agreement IDs belonging to the current user. Only items covered by at least one of there agreements will be returned.
- tr?: "h" | "d" | "w" | "m" | "y" - Time range: last hour, day, week, month, or year.
- title: string -
- email: string - The email address to send emails to.
- schedule: string - A cron expression.
- timezone?: string - A valid time zone name

Returns

Promise<notification>

Example

api.content
  .updateNotificationScheduledEmail(
    'image',
    '4a37869c-808f-496f-b549-3da0821ce187',
    {
      q: 'panda',
      p: ['FOGNRE', '-FOGNREEJ'],
      agr: [20031, 20035],
      tr: 'w',
      title: 'my scheduled email notification',
      email: '[email protected]',
      schedule: '0 0 12 * * MON-FRI',
      timezone: 'Europe/Stockholm',
    }
  )
  .then((result) => {
    // do something with result
  })

updateNotificationStream(mediaType, id, parameters)

Update an existing content stream

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.
id: string - An notification UUID string.
parameters:
- q?: string - A query string used for free text searching.
- p?: Array<string> - A list of product codes. Only items matching at least one of these codes will be returned. The list of current product codes is here. Individual product codes may be prefixed with a '-' sign, indicating that the code should instead be excluded from the search result.
- agr?: Array<number> - A list of customer agreement IDs belonging to the current user. Only items covered by at least one of there agreements will be returned.
- tr?: "h" | "d" | "w" | "m" | "y" - Time range: last hour, day, week, month, or year.
- title: string -

Returns

Promise<notification>

Example

api.content
  .updateNotificationStream('image', '4a37869c-808f-496f-b549-3da0821ce187', {
    q: 'panda',
    p: ['FOGNRE', '-FOGNREEJ'],
    agr: [20031, 20035],
    tr: 'w',
    title: 'my stream notification',
  })
  .then((result) => {
    // do something with result
  })

getNotificationStream(mediaType, id, parameters)

Read new items from a content stream

This is a HTTP long-poll request that consumes items from a previously created notification stream. It will hang until content is available, or a pre-determined number of seconds (given by the wait parameter) has passed, whichever comes first. In the latter case, the response code will still be HTTP 200, but the hits property of the result body will be an empty array. Note that this endpoint is not idempotent; calling it repeatedly will yield different results depending on the current contents of the stream. Notification streams expire after 5 minutes of client inactivity.

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.
id: string - An notification UUID string.
parameters:
- s?: number - Size of search result.
- layout?: "bare" | "full" - By default the full TTNinjs document is returned for each search hit. This may be too cumbersome for some use cases; for example when the client requests a large search result to be displayed in a list form. This parameter allows the client to control the layout of the items in the search result:
  - full - (default) return the full TTNinjs document
  - bare - return only headline, date, uri, renditions, associations, pubstatus, originaltransmissionreference, copyrightholder. In addition, all associations except the first are stripped away, and renditions will only contain the thumbnail rendition.
- wait?: number - The time (in seconds) to wait for updates before returning an empty result.

Returns

Promise<{ 'hits': Array<ttninjs>;}>

Example

api.content
  .getNotificationStream('image', '4a37869c-808f-496f-b549-3da0821ce187', {})
  .then((result) => {
    // do something with result
  })

removeNotification(mediaType, id)

Remove an existing notification

Arguments

mediaType: "_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" - Only return items of this media type.
id: string - An notification UUID string.

Returns

Promise<string>

Example

api.content
  .removeNotification('image', '4a37869c-808f-496f-b549-3da0821ce187')
  .then((result) => {
    // do something with result
  })

UserV1

getAgreements()

Get the current customer agreements.

Return a list of applicable customer agreements for the current user. An agreement that has a truthy value of isSuperAgreement will override any agreement of Subscription type.

DEPRECATED: This endpoint has been deprecated in favor of /user/v1/user

Arguments

Returns

Promise<Array<agreement>>

Example

api.user.getAgreements().then((result) => {
  // do something with result
})

getOrder(parameters)

Get the order/license history for the current user. If the user has customer admin privileges, include all orders for the whole organization.

Arguments

parameters:
- size?: number -
- start?: number -
- status?: "reported" | "unreported" | "all" -

Returns

Promise<{ 'orders'?: Array<order>;}>

Example

api.user.getOrder({}).then((result) => {
  // do something with result
})

updateOrder(id, order)

Update an unreported order row.

Arguments

id: number -
order?: { 'license'?: { 'uuid': string;}; 'invoiceText'?: string; 'approve': boolean;}

Returns

Promise<order>

Example

api.user.updateOrder().then((result) => {
  // do something with result
})

getProfile()

Get the profile for the current user.

The user profile is an unstructured JSON object containing non-secret application data (settings and such). Web applications are free to access this information as they see fit.

Arguments

Returns

Promise<{ }>

Example

api.user.getProfile().then((result) => {
  // do something with result
})

updateProfile(profile)

Update the profile for the current user.

Replaces the entire user profile with the object passed in the request body.

For more controlled updates of the user profile, use the PUT /user/v1/profile/{property} endpoint.

Arguments

profile?: { }

Returns

Promise<string>

Example

api.user.updateProfile({ property1: 'customValue' }).then((result) => {
  // do something with result
})

getProfileByProperty(property)

Get selected properties of the profile for the current user.

The user profile is an unstructured JSON object containing non-secret application data (settings and such). Web applications are free to access this information as they see fit. Often, applications are not interested in the whole user profile. This endpoint returns only selected properties.

Arguments

property: Array<string> - A list of property names.

Returns

Promise<{ }>

Example

api.user.getProfileByProperty(['property1', 'property2']).then((result) => {
  // do something with result
})

updateProfileByProperty(property, profile)

Update selected properties of the profile for the current user.

Replaces selected properties, but doesn't modify the rest of the user profile. This is a more controlled version of the PUT /user/v1/profile endpoint.

Given a profile object like

{
    "property1": { ... },
    "property2": { ... },
    ...
}

and a property parameter like property1,property2, this endpoint will update the given properties, but leave the rest of the user profile intact. Properties present in profile but not listed in property will not be written. Conversely, properties listed in property but not present in profile will not be overwritten with null.

Arguments

property: Array<string> - A list of property names.
profile?: { }

Returns

Promise<string>

Example

api.user
  .updateProfileByProperty(['property1', 'property2'], {
    property1: 'customValue',
  })
  .then((result) => {
    // do something with result
  })

updateDevice(token, parameters)

Arguments

token: string -
parameters:
- type: "ios" | "ios-sandbox" | "android" - The type of device:
  - ios (for the production environment)
  - ios-sandbox (for the APN sandbox)
  - android
- name?: string - The name of this mobile device.
- model: string - The model of this mobile device.

Returns

Promise<string>

Example

api.user
  .updateDevice(
    '5a21a38a24857b344c66aadade0abf2a748fcacf2ddf466e83e4fcd1cefab66a',
    { type: 'ios', name: 'my iPhone', model: 'iPhone 8' }
  )
  .then((result) => {
    // do something with result
  })

removeDevice(token)

Unregister a mobile device.

Arguments

token: string -

Returns

Promise<string>

Example

api.user
  .removeDevice(
    '5a21a38a24857b344c66aadade0abf2a748fcacf2ddf466e83e4fcd1cefab66a'
  )
  .then((result) => {
    // do something with result
  })

getOrganization()

Get information about the organization that the current user belongs to.

Arguments

Returns

Promise<organization>

Example

api.user.getOrganization().then((result) => {
  // do something with result
})

getOrganizationUsers()

List the users belonging to the same organization as the current user. Requires the user to have the admin access level, and the token to have the admin scope.

Arguments

Returns

Promise<Array<userBase>>

Example

api.user.getOrganizationUsers().then((result) => {
  // do something with result
})

addOrganizationUser(user)

Create a new user for the same organization as the current user. Requires the user to have the admin access level, and the token to have the admin scope.

Arguments

user?: { 'firstName': string; 'lastName': string; 'emailAddress': string; 'phoneNumber'?: phoneNumber; 'department'?: string; 'access'?: access;}

Returns

Promise<user>

Example

api.user.addOrganizationUser().then((result) => {
  // do something with result
})

getOrganizationUser(id)

Get information about a user belonging to the same organization as the current user. Requires the user to have the admin access level, and the token to have the admin scope.

Arguments

id: number - A user ID

Returns

Promise<user>

Example

api.user.getOrganizationUser(123).then((result) => {
  // do something with result
})

updateOrganizationUser(id, user)

Update a user belonging to the same organization as the current user. Requires the user to have the admin access level, and the token to have the admin scope.

Arguments

id: number - A user ID
user?: { 'firstName'?: string; 'lastName'?: string; 'emailAddress'?: string; 'phoneNumber'?: phoneNumber; 'department'?: string; 'access'?: access;}

Returns

Promise<user>

Example

api.user.updateOrganizationUser(123).then((result) => {
  // do something with result
})

getUser()

Get information about the current user.

Arguments

Returns

Promise<user>

Example

api.user.getUser().then((result) => {
  // do something with result
})

CollectionV1

getCollections()

List all collections

Returns a list of all collections belonging to the current user.

Arguments

Returns

Promise<Array<collection>>

Example

api.collection.getCollections().then((result) => {
  // do something with result
})

addCollection(collection)

Create a new collection.

Creates an new named collection for the current user. This operation is asynchronous, and there may be a delay before the change is visible using the GET /collection/v1/collection endpoint.

Arguments

collection: { 'name': string; 'public'?: boolean;}

Returns

Promise<collection>

Example

api.collection.addCollection({ name: 'my collection' }).then((result) => {
  // do something with result
})

getCollection(id)

Get collection properties and contents

Returns all properties and contents of a single collection.

Arguments

id: string - ID of a collection.

Returns

Promise<collectionItem>

Example

api.collection.getCollection('123').then((result) => {
  // do something with result
})

updateCollection(id, collection)

Update collection properties

Updates an existing collection belonging to the current user. This operation is asynchronous, and there may be a delay before the change is visible using the GET /collection/v1/collection endpoint.

Arguments

id: string - ID of a collection.
collection: { 'name': string; 'public'?: boolean;}

Returns

Promise<collection>

Example

api.collection
  .updateCollection('123', { name: 'my collection' })
  .then((result) => {
    // do something with result
  })

removeCollection(id)

Remove an existing collection

Removes an existing collection belonging to the current user. This operation is asynchronous, and there may be a delay before the change is visible using the GET /collection/v1/collection endpoint.

Arguments

id: string - ID of a collection.

Returns

Promise<string>

Example

api.collection.removeCollection('123').then((result) => {
  // do something with result
})

addCollectionItems(id, items)

Add items to collection

Adds any number of items to a given collection belonging to the current user. The items must exist in the content database and be visible for the user. If not, this call will still return successfully, but the collection remain unchanged. This operation is asynchronous, and there may be a delay before changes are visible using the GET /collection/v1/collection/{id} endpoint.

Arguments

id: string - ID of a collection.
items: Array<{ 'uri': string;}>

Returns

Promise<string>

Example

api.collection
  .addCollectionItems('123', [{ uri: 'http://tt.se/media/image/sdltd8f4d87' }])
  .then((result) => {
    // do something with result
  })

removeCollectionItems(id, items)

Remove items from collection

Removes any number of items from a given collection belonging to the current user. If one or more items do not currently belong to the collection, this call will still return successfully, but those items will be ignored. This operation is asynchronous, and there may be a delay before changes are visible using the GET /collection/v1/collection/{id} endpoint.

Arguments

id: string - ID of a collection.
items: Array<{ 'uri': string;}>

Returns

Promise<string>

Example

api.collection
  .removeCollectionItems('123', [
    { uri: 'http://tt.se/media/image/sdltd8f4d87' },
  ])
  .then((result) => {
    // do something with result
  })

Exported types

Interface ttninjs

interface ttninjs {
  uri: string
  type?:
    | 'text'
    | 'audio'
    | 'video'
    | 'picture'
    | 'graphic'
    | 'composite'
    | 'planning'
    | 'component'
    | 'event'
  mimetype?: string
  representationtype?: 'complete' | 'incomplete' | 'associated'
  profile?: 'PUBL' | 'DATA' | 'INFO' | 'RAW'
  version?: string
  firstcreated?: string
  versioncreated?: string
  contentcreated?: string
  versionstored?: string
  embargoed?: string
  embargoedreason?: string
  date?: string
  datetime?: string
  enddate?: string
  enddatetime?: string
  job?: string
  pubstatus?: 'usable' | 'withheld' | 'canceled' | 'replaced' | 'commissioned'
  urgency?: number
  copyrightholder?: string
  copyrightnotice?: string
  usageterms?: string
  ednote?: string
  language?: string
  week?: number
  webprio?: number
  newsvalue?: 1 | 2 | 3 | 4 | 5 | 6
  source?: string
  commissioncode?: string
  description_text?: string
  description_usage?: string
  body_text?: string
  body_html5?: string
  body_richhtml5?: string
  body_event?: {
    arena?: string
    city?: string
    address?: string
    country?: string
    eventurl?: string
    eventphone?: string
    eventweb?: string
    organizer?: string
    organizeraddress?: string
    organizercity?: string
    organizercountry?: string
    organizerurl?: string
    organizerphone?: string
    organizermail?: string
    eventstatus?: string
    eventstatus_text?: string
    region?: string
    region_text?: string
    municipality?: string
    municipality_text?: string
    eventtags?: string
    eventtype?: string
    eventtype_text?: string
    note_extra?: string
    note_pm?: string
    accreditation?: string
    extraurl?: string
    createddate?: string
    createdby?: string
    changeddate?: string
    changedby?: string
    courtcasenumber?: string
  }
  body_sportsml?: string
  body_pages?: {}
  commissionedby?: Array<string>
  person?: Array<{
    name?: string
    rel?: string
    scheme?: string
    code?: string
    contactinfo?: Array<contactinfoType>
  }>
  organisation?: Array<{
    name?: string
    rel?: string
    scheme?: string
    code?: string
    symbols?: Array<{
      ticker?: string
      exchange?: string
      symboltype?: string
      symbol?: string
    }>
    contactinfo?: Array<contactinfoType>
  }>
  place?: Array<{
    name?: string
    rel?: string
    scheme?: string
    code?: string
    geometry_geojson?: {
      type?: 'Point'
      coordinates?: Array<number>
    }
    contactinfo?: Array<contactinfoType>
  }>
  subject?: Array<{
    name?: string
    rel?: string
    scheme?: string
    code?: string
    creator?: string
    relevance?: number
    confidence?: number
  }>
  event?: Array<{
    name?: string
    rel?: string
    scheme?: string
    code?: string
  }>
  object?: Array<{
    name?: string
    rel?: string
    scheme?: string
    code?: string
  }>
  infosource?: Array<{
    name?: string
    rel?: string
    scheme?: string
    code?: string
    contactinfo?: Array<contactinfoType>
  }>
  title?: string
  byline?: string
  bylines?: Array<{
    byline?: string
    firstname?: string
    lastname?: string
    role?: string
    email?: string
    jobtitle?: string
    internal?: string
    phone?: string
    initials?: string
    affiliation?: string
  }>
  headline?: string
  slug?: string
  slugline?: string
  located?: string
  charcount?: number
  wordcount?: number
  renditions?: {}
  associations?: {}
  altids?: {
    originaltransmissionreference?: string
  }
  originaltransmissionreference?: string
  trustindicator?: Array<{
    scheme?: string
    code?: string
    title?: string
    href?: string
  }>
  $standard?: {
    name?: string
    version?: string
    schema?: string
  }
  genre?: Array<{
    name?: string
    scheme?: string
    code?: string
  }>
  expires?: string
  rightsinfo?: {
    langid?: string
    linkedrights?: string
    encodedrights?: string
  }
  signals?: {
    pageproduct?: string
    multipagecount?: number
    paginae?: Array<string>
    pagecode?: string
    pagevariant?: string
    updatetype?: 'KORR' | 'RÄ' | 'UV'
    retransmission?: boolean
  }
  product?: Array<{
    name?: string
    scheme?: string
    code?: string
  }>
  replacing?: Array<string>
  replacedby?: string
  assignments?: {}
  revisions?: Array<{
    uri: string
    slug?: string
    replacing?: Array<string>
    versioncreated?: string
  }>
  sector?: 'INR' | 'UTR' | 'EKO' | 'KLT' | 'SPT' | 'FEA' | 'NOJ' | 'PRM'
  fixture?: Array<{
    name?: string
    rel?: string
    scheme?: string
    code?: string
  }>
  advice?: Array<{
    role?: 'publish'
    environment?: Array<{
      code?: string
      scheme?: string
    }>
    importance?: {
      code?: string
      scheme?: string
    }
    lifetime?: {
      code?: string
      scheme?: string
    }
  }>
}

Interface access

interface access {
  admin?: boolean
  mediebank?: boolean
}

Interface address

interface address {
  street?: string
  box?: string
  zipCode?: string
  city?: string
  country?: string
}

Interface agreement

interface agreement {
  id?: number
  description?: {}
  type?: 'Subscription' | 'Direct' | 'Normal' | 'Sketch'
  isSuperAgreement?: boolean
  products?: Array<product>
}

Interface agreement2

interface agreement2 {
  id: number
  name?: string
  type: agreementType
  description?: string
  expires?: string
  superAgreement: boolean
  products: Array<product2>
  prepaids?: {
    total: number
    remaining: number
  }
}

Interface agreementType

interface agreementType "Subscription" | "Direct" | "Normal" | "Prepaid";

Interface collection

interface collection {
  accessed: string
  content: Array<string>
  removedContent?: Array<{
    uri?: string
    headline?: string
    description_text?: string
    timestamp?: string
  }>
  created: string
  id: string
  modified?: string
  name: string
  owner: string
  public: boolean
}

Interface collectionItem

interface collectionItem {
  accessed: string
  content: Array<string>
  removedContent?: Array<{
    uri?: string
    headline?: string
    description_text?: string
    timestamp?: string
  }>
  created: string
  id: string
  modified?: string
  name: string
  owner: string
  public: boolean
  items: Array<ttninjs>
}

Interface error

interface error {
  errorCode?: string
  location?: string
  message?: string
  path?: string
}

Interface errors

interface errors {
  errors?: Array<error>
}

Interface facet

interface facet {
  key?: string
  count?: number
}

Interface license

interface license {
  uuid?: string
  period?: 'Year' | 'Month' | 'Single'
  volume?: string
  price?: monetaryAmount
  description?: string
  product: product
}

Interface monetaryAmount

interface monetaryAmount string;

Interface order

interface order {
  id: number
  item: {
    uri?: string
    headline?: string
    byline?: string
    source?: string
  }
  price: {
    name: string
    description?: string
    license: license
    agreement: {
      id: number
      name?: string
      type: agreementType
    }
  }
  invoiceText?: string
  created: string
  downloadableUntil: string
  reportingDeadline?: string
  reported?: string
  approved?: boolean
  manual?: boolean
}

Interface notification

interface notification {
  id: string
  title?: string
  type: 'mobile' | 'email' | 'scheduled-email' | 'stream'
  mediaType:
    | '_all'
    | 'image'
    | 'video'
    | 'graphic'
    | 'text'
    | 'feature'
    | 'page'
    | 'planning'
    | 'calendar'
  q?: string
  p?: Array<string>
  agr?: Array<number>
  schedule?: string
  timezone?: string
  email?: string
}

Interface organization

interface organization {
  id: number
  name?: string
  currency?: string
  country?: string
  address: {
    visit?: address
    postal?: address
    billing?: address
  }
  phoneNumber: phoneNumberDirect
}

Interface phoneNumber

interface phoneNumber {
  direct?: string
  mobile?: string
}

Interface phoneNumberDirect

interface phoneNumberDirect {
  direct?: string
}

Interface product

interface product {
  name?: string
  description?: {}
  code?: string
}

Interface product2

interface product2 {
  id: number
  name?: string
  description?: string
  code: string
}

Interface user

interface user {
  id: number
  customerId?: number
  userName: string
  firstName?: string
  lastName?: string
  emailAddress?: string
  department?: string
  phoneNumber: phoneNumber
  agreements: Array<agreement2>
  access: access
  active: boolean
}

Interface userBase

interface userBase {
  id: number
  customerId?: number
  userName: string
  firstName?: string
  lastName?: string
  emailAddress?: string
  department?: string
  active: boolean
}

Interface contactinfoType

interface contactinfoType {
  type?: string
  role?: string
  lang?: string
  name?: string
  value?: string
  address?: {
    lines?: Array<string>
    locality?: string
    area?: string
    postalcode?: string
    country?: string
  }
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@ttab/api-client

Getting started

Prerequisites

Obtaining an OAuth2 token

Searching

Streaming data

The ContentStream class

Methods

Events

Error handling

Example

Errors

API Reference

ContentV1

search(mediaType, parameters)

Arguments

Returns

Example

stream(mediaType, parameters)

Arguments

Returns

Example

getNotifications(mediaType)

Arguments

Returns

Example

addNotificationMobile(mediaType, parameters)

Arguments

Returns

Example

addNotificationEmail(mediaType, parameters)

Arguments

Returns

Example

addNotificationScheduledEmail(mediaType, parameters)

Arguments

Returns

Example

addNotificationStream(mediaType, parameters)

Arguments

Returns

Example

updateNotificationMobile(mediaType, id, parameters)

Arguments

Returns

Example

updateNotificationEmail(mediaType, id, parameters)

Arguments

Returns

Example

updateNotificationScheduledEmail(mediaType, id, parameters)

Arguments

Returns

Example

updateNotificationStream(mediaType, id, parameters)

Arguments

Returns

Example

getNotificationStream(mediaType, id, parameters)

Arguments

Returns

Example

removeNotification(mediaType, id)

Arguments

Returns

Example

UserV1

getAgreements()

Arguments

Returns

Example

getOrder(parameters)

Arguments

Returns