@salla.sa/twilight 2.0.283 → 2.0.285

package/README.md

@@ -1,12 +1,216 @@
-# Salla Twilight
 
+<div id="top"></div>
 
-### Events `salla.event` base on [EventEmitter2](https://github.com/EventEmitter2/EventEmitter2)
+<br />
+<div align="center">
+     <a href="https://salla.dev">
+        <img src="https://salla.dev/wp-content/themes/salla-portal/dist/img/salla-logo.svg" alt="Logo" width="80" height="80">
+     </a>
+     <h1 align="center">Twilight JS APIs</h1>
+     <p align="center">
+         A JavaScript SDK for the Salla storefront APIs provides helper methods, or REST API endpoints, that allow communication between the frontend and backend. 
+          <br />
+          <a href="https://salla.dev/"><strong>Explore our blogs »</strong></a>
+          <br />
+          <br />
+          <a href="https://github.com/SallaApp/Salla-CLI/issues/new">Report Bug</a> ·
+          <a href="https://github.com/SallaApp/Salla-CLI/discussions/new">Request Feature</a> . 
+          <a href="https://t.me/salladev">&lt;/Salla Developers&gt;</a> .
+          <a href="https://salla.stoplight.io/docs/twilight-themes-documentation/3ac843cae76a2-overview">Official Documentation</a> 
+     </p>
+</div>
 
+<!-- TABLE OF CONTENTS -->
+<details open>
+     <summary>Table of Contents</summary>
+     <ol>
+          <li>
+               <a href="#overview">Overview</a>
+          </li>
+          <li>
+               <a href="#getting-started">Getting Started</a>
+               <ul>
+               <li><a href="#sdks-main-apis">SDK's main APIs</a></li>
+              <li><a href="#use-cases">Use cases</a></li>
+               </ul>
+               <li><a href="#installation">Installation</a></li>
+                         <ul>
+               <li><a href="#initialization">Initialization</a></li>
+               </ul>
+          <li><a href="#usage">Usage</a></li>
+                         <ul>
+               <li><a href="#basic-configuration">Basic configuration </a></li>
+               </ul>
+          <li><a href="#support">Support</a></li>
+          <li><a href="#contributing">Contributing</a></li>
+          <li><a href="#credits">Credits</a></li>
+          <li><a href="#license">License</a></li>
+          </li>
+     </ol>
+</details>
+<!-- Overview -->
 
+## Overview
 
-# Installing
+**Twilight** comes with a **JavaScript SDK** for the Salla storefront APIs. This is to provide the developers with helper methods, or REST API endpoints, that allow communication between the frontend and backend. As a result, developers may use these methods to make merchants' stores dynamic after using the API features and data. In this documentation, we will be referring to it as **Twilight JS SDK** for short.
 
+## Getting Started
+**SDK** stands for "software development kit," and it refers to a library for interacting with a specific REST API using JavaScript. 
+
+### SDK's main APIs
+The main parts of the **Twilight JS SDK** includes REST API endpoints that ease the actions related to the APIs request, such as:
+- **Authorization APIs:** Several endpoints for customer logging in, logging out, and many more. 
+- **Cart APIs:** Customer's cart list of endpoints.
+- **Comments APIs:** Group of endpoints related to the customer comments, or feedback, on product or page.
+- **Currency APIs:** Group of endpoints related to the store's currencies list.
+- **Order APIs:** Customer's orders related endpoints.
+- **Product APIs**: Product related endpoints.
+- **Profile APIs:** Customer's profile endpoints. 
+- **Rating APIs:** endpoints related to the store, product, order, shipping rating.
+- **Wishlist APIs:** Customer's wishlist endpoints. 
+
+### Use cases
+Following are some of the possible uses of the Twilight JS SDK:
+- Authenticating customers and allowing them to edit account details.
+- Adding a product directly from the products list to the customer art.
+- Returning the price of a product.
+- Adding a product to the customer's wishlist.
+- Rating the shipping company responsible for delivering orders.
+- And many more!
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+## Installation 
+**Twilight JS SDK** can be installed from the `npm` using the following commands:
+
+```npm title="NPM Installation Command"
+npm install @salla.sa/twilight-js --save
+```
+
+```yarn title="Yarn Installation Command"
+yarn add @salla.sa/twilight-js
+```
+
+### Initialization
+
+The following snippet of code will give the basic version of the SDK where the configurations are set to their minimum requirements, for example, store URL. The method `salla.init()` is used to setup and initialize the SDK. 
+
+```js
+<script>
+  let url = "https://my_store.test/";
+  salla.init({debug: true, store: {api: url + "api/v1/", url: url}});
+</script>
+```
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+## Usage
+
+As a result of the SDK initialization, the developer will be able to use any of the SDK's main APIs. For example,  the method `addItem` adds an item into the cart, the developer may call the method `addItem` as follows:
+
+```js
+salla.cart.addItem({
+    id: 1234,
+    quantity: 1,
+    notes: "please i need to get the red color"
+}).then((response) => {
+    /* add your code here */
+});
+```
+In addition to the above example, the method `addItem` may adds an item with multiple options to the carts as follows:
+```js
+salla.cart.addItem({
+    id: 1234,
+    quantity: 1,
+    options: {
+      117414452: 11232214, // option value id (select choice)
+      117416632: "http://option-value-as-url-of-image.com",
+      117411132: "option value as string"
+    },
+    notes: "please i need to get the red color"
+}).then((response) => {
+    /* add your code here */
+});
+```
+
+Furthermore, a large number of store events will be available for use. Thus, the developer's theme may be configured to respond automatically to a variety of activities, such as:
+
+- The user requested an Access Code to perform a login, however, the code was not sent. For this scenario, using the method `salla.event.auth.onCodeNotSent()` can be used.
+
+- A new item has been added to the cart via the `salla.cart.event.onItemAdded()` method.
+
+- The user added a new item to the Wishlist using the method `salla.event.wishlist.onAdded()`.
+
+Full example for that would be the event `onItemAdded` which is triggered when adding an item to the cart is done without having any errors coming back from the backend:
+```js
+salla.cart.event.onItemAdded((response) => {
+  console.log(response)
+});
+```
+On the over hand, the event `onItemAddedFailed` is triggered when adding an item to the cart is not completed and an error has occurred. For example, the id of the product to be added to the cart was not found.
+```js
+salla.cart.event.onItemAddedFailed((errorMessage) => {
+  console.log(errorMessage)
+});
+```
+
+
+### Basic configuration 
+
+Aside from calling the APIs, the developer has the ability to configure the Twilight engine to meet the needs of his theme. This list of the available configurations can be found in this [article](https://salla.stoplight.io/docs/twilight-themes-documentation/ZG9jOjQ4OTE2NDQ5-configuration). For this purpose, the method `salla.config.get()` is used to retrieve a configuration value, while `salla.config.set()` is used to set a configuration value.
+
+#### Set configuration value
+The developer may set the debug mode to be activated. That is to state, the theme will be run in a debugger. This means that the debugger keeps track of everything that happens while the theme is running.
+
+```js
+salla.config.set('debug', true)
+```
+
+#### Get configuration value
+Similarly, the developer can use the method'salla.config.get()' to get any value from the configuration file. To retrive simaple value such as the user Id, the following syntax can be followed:
+
+```js
+salla.config.get('user.id’)
 ```
-npm install @salla.sa/twiglight
+
+Furthermore, if the required value is nested inside an inner value, such as a currency code, the following syntax can be followed:
+
+```js
+salla.config.get('curremcies.SAR.code’)
 ```
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+## Support
+
+The team is always here to help you. Happen to face an issue? Want to report a bug? You can submit one here on Github using the [Issue Tracker](https://github.com/SallaApp/twilight-vscode-extension/issues/new). If you still have any questions, please contact us via the [Telegram Bot](https://t.me/SallaSupportBot) or join in the Global Developer Community on [Telegram](https://t.me/salladev).
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+## Contributing
+
+Contributions are what make the open-source community such an amazing place to learn, inspire, and create.
+Any contributions you make are **greatly appreciated**.
+
+If you have a suggestion that would make this better, please fork the repo and create a pull request.
+You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+## Credits
+
+- [Salla](https://github.com/sallaApp)
+- [All Contributors](../../contributors)
+  
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+## License
+
+The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
+
+<p align="right">(<a href="#top">back to top</a>)</p>