@salla.sa/twilight 3.0.0-alpha.0 → 3.0.0

package/README.md

@@ -1,4 +1,3 @@
-
 <div id="top"></div>
 
 <br />
@@ -49,7 +48,29 @@
 
 ## Overview
 
-**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.
+The Twilight JS SDK (`@salla.sa/twilight`) is the core package of the Twilight Framework, providing a comprehensive JavaScript interface for Salla's storefront APIs. It enables theme developers to easily communicate with Salla's backend services, handle events, manage state, and build interactive e-commerce experiences.
+
+### Architecture
+
+The Twilight Framework consists of several packages working together:
+
+1. **@salla.sa/base**: Foundation layer with core utilities and services
+2. **@salla.sa/twilight** (this package): Main SDK for Salla themes
+3. **@salla.sa/twilight-components**: Web components for Salla themes
+4. **@salla.sa/twilight-tailwind-theme**: Tailwind CSS theme for Salla themes
+5. **@salla.sa/applepay**: Apple Pay integration for Salla
+
+This modular architecture allows for better separation of concerns, more maintainable code, and the ability to use only the parts of the framework that are needed for a specific application.
+
+### Key Features
+
+- **API Integration**: Pre-built methods for all Salla API endpoints
+- **Event System**: Powerful event handling for real-time updates
+- **Authentication**: Seamless user authentication and session management
+- **Cart Management**: Complete shopping cart functionality
+- **Multilingual Support**: Built-in localization capabilities
+- **Version Management**: Easy access to package versions via `Salla.versions`
+- **Optimized Bundle**: Tree-shakable modules for minimal production builds
 
 ## Getting Started
 **SDK** stands for "software development kit," and it refers to a library for interacting with a specific REST API using JavaScript. 
@@ -215,6 +236,49 @@ Furthermore, if the required value is nested inside an inner value, such as a cu
 salla.config.get('currencies.SAR.code’)
 ```
 
+#### Accessing Version Information
+
+The Twilight Framework provides easy access to version information for all packages through the `Salla.versions` object:
+
+```js
+// Get the version of the core package
+console.log(Salla.versions.twilight); // e.g., "v2.14.145"
+
+// Get the version of the base package
+console.log(Salla.versions.base); // e.g., "v2.14.143"
+```
+
+This is particularly useful for debugging, support, and ensuring compatibility between different parts of the framework.
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+### WebMCP (tools for in-browser AI agents)
+
+Twilight can register [WebMCP](https://webmachinelearning.github.io/webmcp/) tools so an AI agent running in the shopper's browser can search, fill the cart and head to checkout. The tools call the regular SDK (`salla.cart.*`, `salla.product.*`) in the shopper's own tab, so they fire the normal cart events and the cart badge and mini-cart update as they would for a click. They never call the `/mcp` worker, whose carts are not the tab's cart.
+
+| Tool | Read-only | What it does |
+|------|-----------|--------------|
+| `search_products` | yes | Search the store's products by keyword (`query`, optional `limit`). |
+| `get_product` | yes | Product details by `product_id`. |
+| `get_cart` | yes | The shopper's current cart: items, totals, coupon. |
+| `add_to_cart` | no | Add `product_id` (`quantity`, and `options` keyed by option id for products that need them). |
+| `update_cart_item` | no | Change the quantity of a cart item. |
+| `remove_cart_item` | no | Remove a cart item. |
+| `apply_coupon` | no | Apply a coupon code. |
+| `go_to_checkout` | no | Navigate to checkout (guests go to login first). It only navigates; **it never places an order**, the shopper pays on the checkout page. |
+
+Failures come back as `{ isError: true, content: [...] }` with the API's own message.
+
+**Off by default.** Stores opt in through the config passed to `Salla.init`:
+
+```js
+Salla.init({ store: { id: 1234 }, webmcp: { enabled: true } });
+```
+
+Only the boolean `true` (or `'true'` / `1`) turns it on. Salla Store renders this value for you from `TWILIGHT_WEBMCP_ENABLED` (all stores) or the `themes::webmcp.enabled` store setting; set it back to `false` to switch the tools off. No Twilight release is involved.
+
+**Browser support.** Needs a browser that implements WebMCP and an HTTPS page. It looks for `document.modelContext` first, then `navigator.modelContext`, and does nothing when neither exists (all other browsers, including current Firefox and Safari) or on HTTP. In Chrome 146+ the API is behind the `chrome://flags/#enable-webmcp-testing` flag ("WebMCP for testing"). Registering the same tool twice (for example when init runs twice) is tolerated.
+
 <p align="right">(<a href="#top">back to top</a>)</p>
 
 ## Support
@@ -251,4 +315,3 @@ You can also simply open an issue with the tag "enhancement". Don't forget to gi
 The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
 
 <p align="right">(<a href="#top">back to top</a>)</p>
-