Global

Methods

boxToken(options, content) → {RichToken}

Source:

Create a new box token. Used for adding space to layouts.

Parameters:
Name Type Description
options Object

Options for the box
content RichToken | Array.<RichToken>

The contents of the box.
Returns:

Box Token

Type
RichToken

conditionalToken(media, nsfw, content, alternative) → {RichToken}

Source:

Create a new conditional token. Conditional tokens allow you to hide part of a rich token document when conditions regarding user settings are met.

Parameters:
Name Type Description
media Boolean

Whether or not this content contains media
nsfw Boolean

Whether or not this content is NSFW
content RichToken | Array.<RichToken>

Rich tokens to display when this condition matches.
alternative RichToken | Array.<RichToken>

Rich tokens to display when this condition does not match.
Returns:

Conditonal Token

Type
RichToken

flexToken(options, content) → {RichToken}

Source:

Create a new flex token. Used for creating responsive layouts.

Parameters:
Name Type Description
options Object

Options for the flex
content RichToken | Array.<RichToken>

The contents of the flex.
Returns:

Flex Token

Type
RichToken

formatSize(bytes) → {String}

Source:

Format a file-size for readability.

Parameters:
Name Type Description
bytes Number

The number of bytes
Returns:

Formatted filesize.

Type
String

formatToken(type, value, optionsopt) → {RichToken}

Source:

Create a new format token. Format tokens tell a client how they should format a given value for rendering.

See the responses section on format tokens for more details.

Parameters:
Name Type Attributes Description
type String

The format type.
value *

The value that should be formatted.
options Object <optional>

Any additional options for the formatter.
Returns:

Format Token

Type
RichToken

galleryToken(…items) → {RichToken}

Source:

Create a new gallery token, containing 1 to 4 items. Galleries constrain the size of their items and arrange them into a grid.

Parameters:
Name Type Attributes Description
items RichToken <repeatable>

The gallery's contents.
Returns:

Gallery Token

Type
RichToken

i18nToken(key, phrase, contentopt) → {RichToken}

Source:

Create a new internationalization token. I18n tokens allow you to have the client localize a string.

See the responses section on I18n tokens for more details.

Parameters:
Name Type Attributes Description
key String

The key for this localization.
phrase String

The phrase to localize.
content Object <optional>

Content to insert into the localized phrase.
Returns:

I18n Token

Type
RichToken

iconToken(name) → {RichToken}

Source:

Create a new icon token. Icon tokens should be rendered as an icon by clients.

See the responses section on icon tokens for more details.

Parameters:
Name Type Description
name String

The name of the icon
Returns:

Icon Token

Type
RichToken

imageToken(url, options) → {RichToken}

Source:

Create a new image token. Used for rendering images.

Parameters:
Name Type Description
url String | URL | BackgroundAwareImage

The URL for the image.
options Object

Options for the image.
Returns:

Image Token

Type
RichToken

linkToken(url, content, optionsopt) → {RichToken}

Source:

Create a new link token. Link tokens tell a client to link to external content.

Parameters:
Name Type Attributes Description
url String | URL

The URL to link to.
content String | RichToken | Array.<RichToken>

The contents of the link as a rich token document.
options Object <optional>

Any additional options for the link token.
Returns:

Link Token

Type
RichToken

normalizeURL(url, base, default_schemeopt) → {URL}

Source:

Normalize a URL.

This adds a scheme to URLs without a scheme, ensures that the scheme is either HTTP or HTTPS, removes search hashes, removes trailing dots from hostnames, and removes garbage query parameters such as utm_ tracking parameters to slim down links for better cache hit rates.

If no base URL is provided and the URL is a relative URL, a RelativeURLError will be thrown. If the scheme is not HTTP or HTTPS, an UnsupportedSchemeError will be thrown.

Parameters:
Name Type Attributes Default Description
url String | URL

The URL to normalize.
base URL

The base URL for processing relative URLs.
default_scheme String <optional>
 'http'

The default scheme to set if a URL has no scheme.
Returns:

The normalized URL

Type
URL

overlayToken(content, layers, optionsopt) → {RichToken}

Source:

Create a new overlay token. Overlay tokens allow you to place aligned content over top of other content.

Parameters:
Name Type Attributes Description
content RichToken | Array.<RichToken>

The overlay's base content
layers Object

Content to layer over the base content
options Object <optional>

Additional options for the overlay token.

Properties
Name Type Attributes Description
background String <optional>

A background color for the overlay.
Returns:

Overlay Token

Type
RichToken

refToken(name) → {RichToken}

Source:

Create a new reference token. Reference tokens allow you to include a shared document fragment. This is useful for reusing parts of the output between short, mid, and full.

Parameters:
Name Type Description
name String

The name of the shared fragment.
Returns:

Reference Token

Type
RichToken

styleToken(options, content) → {RichToken}

Source:

Create a new style token. Applies styles to its content.

Parameters:
Name Type Description
options Object

The styles to apply.
content String | RichToken | Array.<RichToken>

The content to apply them to.
Returns:

StyleToken

Type
RichToken

truncate(str, target, overage, ellipsisopt, break_lineopt, trimopt) → {String}

Source:

Truncate a string. Tries to intelligently break the string in white-space if possible, without back-tracking. The returned string can be up to ellipsis.length + target + overage characters long.

Parameters:
Name Type Attributes Default Description
str String

The string to truncate.
target Number

The target length for the result
overage Number

Accept up to this many additional characters for a better result
ellipsis String <optional>
 '…'

The string to append when truncating
break_line Boolean <optional>
 true

If true, attempt to break at the first LF
trim Boolean <optional>
 true

If true, runs trim() on the string before truncating
Returns:

The truncated string

Type
String

wrapFetch(original) → {function}

Source:

Wrap a fetch API, automatically injecting an abort controller for each request as well as adding support for automatic timeouts.

Parameters:
Name Type Description
original function

The original fetch method to wrap.
Returns:

The wrapped fetch method.

Type
function

Type Definitions

BackgroundAwareImage

Source:
Properties:
Name Type Description
light String

The image to use against light backgrounds
dark String

The image to use against dark backgrounds

BackgroundAwareImage

Type:
  • Object

CacheOptions

Source:
Properties:
Name Type Description
ttl Number

The number of seconds this item should remain cached.

CacheOptions

Type:
  • Object

CacheResult

Source:
Properties:
Name Type Description
hit Boolean

Whether or not the item was found in the cache
value Object

The item from the cache. May be null.

CacheResult

Type:
  • Object

CheckedURL

Source:
Properties:
Name Type Description
URL String

the URL that was checked
unsafe Boolean

Whether or not the URL should be considered unsafe.
shortened Boolean

Whether or not the URL matches a known URL shortener.
flags Array.<String>

A list of reasons why the URL is unsafe.

CheckedURL

Type:
  • Object

ExampleURL

Source:
Properties:
Name Type Attributes Description
url String | URL

The example URL that we're describing.
title String <optional>

A descriptive name for the URL
resolver String <optional>

The name of the resolver. This is added to the ExampleURL automatically in LinkService#getExamples.

Example URL

Type:
  • Object

Field

Source:
Properties:
Name Type Attributes Default Description
name String | RichToken | Array.<RichToken>

The name to display for the field. May be rich tokens.
value String | RichToken | Array.<RichToken>

The value to display for the field. May be rich tokens.
inline Boolean <optional>
 false

Whether or not the field should be displayed in-line with other fields.

Field

Type:
  • Object

RequestContext

Source:
Properties:
Name Type Attributes Default Description
url String | URL

Automatic. The current URL of the request. May change after Resolver#transformURL.
original_url URL

Automatic. The original URL of the request.
request FetchResponse

Automatic. The fetch request object for this request. Not available within Resolver#transformURL.
referrer URL

The referrer of the request. May be changed within Resolver#transformURL to change the Referer header sent with the request.
skip_request Boolean <optional>

If set to true, no fetch request will be performed and instead Resolver#processBody will be called immediately with only null values and this context object.
fetch function <optional>

The version of fetch to use. Useful in case you want to wrap fetch with something to, for example, automatically renew a client credential token when necessary and add it to the request. The custom fetch implementation should wrap our custom fetch with timeout support or provide an equivilent API.
headers Object <optional>

An optional object of headers to send with the request. Has no effect if set outside Resolver#transformURL.
options Object <optional>

An optional object of options to send to fetch when performing the request. Has no effect is set outside Resolver#transformURL.
timeout Number <optional>

The number of miliseconds after which the fetch request should time out. Overrides the default value from the LinkService options. Has no effect if set outside Resolver#transformURL.
follow_redirect Boolean <optional>
 true

Whether or not the Resolver should automatically follow redirects when fetching the resource. Supports Location and Refresh header-based redirects.
cache_key String <optional>

The key to use when reading and writing to the configured cache. If this is not set, the request URL will be used instead. This should be used when more than one URL may describe the same resource. If explicitly set to false, caching will be disabled. This should probably never be done.
cache_opts CacheOptions <optional>

An optional set of extra options to be passed to cache methods. This can be used to override default timeouts, etc. depending on your CacheInterface.
parse String <optional>

Override how the response body should be parsed before Resolver#processBody is called. This can be set in either Resolver#transformURL or Resolver#processHeaders. Valid values are: buffer, json, html, and xml.
response Object <optional>

The data to return as a response from the Resolver for this request. If Resolver#processBody returns null or undefined, this value is returned instead. This can also be used to return data without ever processing the response body by setting it and then returning a falsey value from Resolver#processHeaders.

Request Context

Type:
  • Object

RichToken

Source:
Properties:
Name Type Description
type String

The type of token

Rich Token

Type:
  • Object