@amazon-devices/asset-resolver-lib 1.0.1767254403

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Amazon.com, Inc. or its affiliates.  All rights reserved.
+
+These materials are licensed as "Program Materials" under the Program Materials License Agreement (the "Agreement").  The Agreement is available at https://developer.amazon.com/support/legal/pml.  See the Agreement for the specific terms and conditions of the Agreement.  Capitalized terms not defined in this file have the meanings given to them in the Agreement.  
+
+If you do not agree to the above terms and conditions, you may not use any file in this package. 
+
+YOUR USE OF THE PROGRAM MATERIALS IN OR ASSOCIATED WITH THIS PACKAGE IS AT YOUR SOLE RISK.  IN NO EVENT WILL AMAZON BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, CONSEQUENTIAL, SPECIAL, INCIDENTAL, OR PUNITIVE DAMAGES (INCLUDING FOR ANY LOSS OF GOODWILL, BUSINESS INTERRUPTION, LOST PROFITS OR DATA, OR COMPUTER FAILURE OR MALFUNCTION) ARISING FROM OR RELATING TO SUCH PROGRAM MATERIALS, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, EVEN IF AMAZON HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.  THESE LIMITATIONS AND DISCLAIMERS APPLY EXCEPT TO THE EXTENT PROHIBITED BY APPLICABLE LAW.

package/LICENSE-THIRD-PARTY

@@ -0,0 +1,76 @@
+@amazon-devices/keplerscript-turbomodule-api
+1.0.0 <>
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and its affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+******************************
+
+@react-native/js-polyfills
+0.72.1 <https://github.com/facebook/react-native/tree/v0.72.1/packages/polyfills>
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+******************************
+
+@babel/runtime
+7.27.6 <https://github.com/babel/babel/tree/v7.27.6/packages/babel-runtime>
+MIT License
+
+Copyright (c) 2014-present Sebastian McKenzie and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# AssetResolver
+
+This document will serve as a user guide and will explain library installation (in a KSDK app) and 
+API usage.
+
+### Library Setup
+
+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'
+    ```
+
+### Asset Resolution
+
+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](https://developer.amazon.com/docs/kepler-tv-api/internationalization-developer-guide.html)
+define text resources used in an application and are used by Asset Resolver in its getString() and
+getNumber() APIs.
+
+### Configuration Qualifiers
+
+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.
+
+### Access Control
+
+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.
+
+### Usage
+
+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);
+```