AssetResolver

This document will serve as a user guide and will explain library installation (in a KSDK app) and
API usage.

$3

1. Update the package's package.json file to add the library as a dependency:

``json
"dependencies": {
"@amazon-devices/asset-resolver-lib": "*"
}
`

1. With these changes, the AssetResolver turbo module can be consumed. To include the class and its
types, the following include line should be used:

`js
import { AssetResolver, AssetType } from '@amazon-devices/asset-resolver-lib'
`

$3

As previously mentioned, AssetResolver turbo module is a wrapper for the AssetResolver Application
Framework library. The AssetResolver library provides applications a means of seamless asset
resolution whereby assets are ranked according to device system qualifiers.

Applications can contain assets which are files that can be used for things such as images and text.
Assets must be located in the application's assets directory, and the following directory
structure must be used for AssetResolver API use:

`text
└── assets
├── image
├── raw
└── text
`

These directories will hold asset files for images, raw files, and text-defining files,
respectively. These are the supported asset types in the AssetResolver.

For text localization, Asset Resolver expects text asset files to use the puff.json format for
defining string and numeric values.
PUFF-J files
define text resources used in an application and are used by Asset Resolver in its getString() and
getNumber() APIs.

$3

The AssetResolver's APIs resolve assets based on the system's current configuration qualifiers.
These are values which define certain device properties such as locale, UI mode, and so on.

For example, the qualifier locale can take values en-US, es-AR, or es-SP. This qualifier will
directly influence which assets are resolved.

`text
└── assets
├── image
├── raw
└── text
├── en
│   └── strings.puff.json
├── en-US
│   └── strings.puff.json
├── es
│   └── strings.puff.json
├── es-AR
│   └── strings.puff.json
└── strings.puff.json
`

In the above asset directory structure, the file strings.puff.json is defined in multiple
directories: one for each locale and one in text to act as a default. Depending on the current
system configuration qualifiers, the AssetResolver will resolve text based on the most appropriate
match; if there is none, the default file will be used.

_NOTE_: when an application supports a locale (such as en-GB), it must also define support
for that locale's default qualifier (in this case en).

_NOTE_: defining a default asset file is recommended as it ensures there is always an asset
matched in case asset resolution fails.

If the system configuration qualifier for locale is es-AR, then the file
assets/text/es-AR/strings.puff.json will be chosen when using the AssetResolver APIs. If multiple
locales contain the same text assets, symbolic links to a single asset file may be used to save
device storage space.

_NOTE_: only locale is supported as a configuration qualifier to resolve assets around.

$3

The AssetResolver APIs are not access-controlled. AssetResolver APIs only execute within an
application's subset of the device's filesystem. Moreover, other applications cannot explicitly
resolve assets from another application, ensuring app-to-app isolation.

$3

The AssetResolver is an application library that allows retrieval of assets from packages. These
assets are resolved based on various system qualifiers such as locale, day/night mode, UI mode, etc.
Assets can be text-based, images, or raw files.

The AssetResolver turbo module provides various APIs which packages may use to retrieve asset values
as well as paths which will be demonstrated below.

#### AssetConfiguration type

Certain APIs take in an AssetConfiguration object. This object is used to specify which qualifiers
should be used when resolving assets. Currently locale is supported.

#### getString()

In order to retrieve an internationalized string value, the getString() API should be used. This
API takes in the identifier of the string being queried and an optional configuration object which
specifies which qualifiers should be used in asset resolution.

On failure, this API will throw an Error whose message indicates the error condition.

`js
const stringResult = AssetResolver.getString("welcome-string");

console.log("string value: {}", stringResult.value);
console.log("string direction: {}", stringResult.dir);

const config = { locale: "fr-CA" };
const stringConfigResult = AssetResolver.getString("welcome-string", config);

console.log("string value: {}", stringConfigResult.value);
console.log("string direction: {}", stringConfigResult.dir);
`

#### getNumber()

In order to retrieve an internationalized number value, the getNumber() API should be used. Similar
to getString(), this takes in a string which is the identifier for the number value being queried.
Furthermore, the API also takes in an optional configuration object which specifies which
qualifiers should be used in asset resolution.

This API similarly throws an Error if there is an issue in execution.

`js
const numberResult = AssetResolver.getNumber("numeral");

console.log("number value: {}", numberResult);

const config = { locale: "en-US" };
const numberConfigResult = AssetResolver.getNumber("numeral", config);

console.log("number value: {}", numberConfigResult);
``