@froomle/frontend-sdk 0.0.17 → 0.0.19

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+      Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+      stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+      that You distribute, all copyright, patent, trademark, and
+      attribution notices from the Source form of the Work,
+      excluding those notices that do not pertain to any part of
+      the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+      distribution, then any Derivative Works that You distribute must
+      include a readable copy of the attribution notices contained
+      within such NOTICE file, excluding those notices that do not
+      pertain to any part of the Derivative Works, in at least one
+      of the following places: within a NOTICE text file distributed
+      as part of the Derivative Works; within the Source form or
+      documentation, if provided along with the Derivative Works; or,
+      within a display generated by the Derivative Works, if and
+      wherever such third-party notices normally appear. The contents
+      of the NOTICE file are for informational purposes only and
+      do not modify the License. You may add Your own attribution
+      notices within Derivative Works that You distribute, alongside
+      or as an addendum to the NOTICE text from the Work, provided
+      that such additional attribution notices cannot be construed
+      as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,399 +1,8 @@
-# Javascript Library Documentation
+# Froomle Frontend SDK
 
-1. [Framework-Agnostic Recommendation Proxy](#framework-agnostic-recommendation-proxy)
-2. [React Integration Helpers](#react-integration-helpers)
-3. [JavaScript Modules](#javascript-modules)
-4. [Supporting a New Framework](#supporting-a-new-framework)
+[![NPM Version](https://img.shields.io/npm/v/%40froomle%2Ffrontend-sdk)](https://www.npmjs.com/package/@froomle/frontend-sdk)
+[![NPM Downloads](https://img.shields.io/npm/dm/%40froomle%2Ffrontend-sdk)](https://www.npmjs.com/package/@froomle/frontend-sdk)
 
-## Framework-Agnostic Recommendation Proxy
+Public documentation is located at:
 
-To support multiple frontend frameworks (React and others) while preserving a single shared SDK core, the SDK uses a **proxy-based recommendation wrapper**.
-
-This mechanism allows recommendation items to be **used immediately**, even though the underlying data may not yet be available.
-
----
-
-### Problem Being Solved
-
-Frameworks like React expect values to be:
-
-- referentially stable
-- accessible during render
-- optionally async-aware
-
-At the same time, the SDK:
-
-- batches recommendation requests
-- resolves them later via a single backend call
-- relies on shared static state
-- cannot expose all internal APIs directly
-
-Returning a raw `Promise<RecommendationItem>` would not work, because components often need to **read fields synchronously**.
-
----
-
-### High-Level Idea
-
-The solution is to return a **Proxy object** that behaves as both:
-
-- a `RecommendationItem`
-- a `PromiseLike<RecommendationItem>`
-
-This proxy:
-
-- intercepts property access
-- defers resolution until recommendations are fulfilled
-- transparently switches to real data once available
-
-From the consumer’s point of view, it behaves like a normal recommendation object that “fills itself in later”.
-
----
-
-### Deferred Request Queue
-
-When a recommendation is requested:
-
-- a deferred promise is created
-- the request is added to a shared queue
-- no backend call is executed immediately
-
-All pending requests are stored in a global request list until they are explicitly fulfilled.
-
-This allows:
-
-- batching multiple requests into one backend call
-- predictable request ordering
-- shared static backend state
-
----
-
-### Fulfilling Recommendations
-
-`fulfillRecommendations()`:
-
-- executes a single backend request for all queued recommendations
-- receives a list of recommendation items
-- resolves each deferred promise with its corresponding item
-- clears the request queue
-
-This function is typically called once per render cycle (for example on application mount in React).
-
----
-
-### Proxy-Based Recommendation Item
-
-The returned object is a JavaScript `Proxy` wrapping an internal recommendation item.
-
-The proxy provides three key behaviors:
-
-- **Property access interception**  
-  When a field is accessed, the proxy either:
-    - returns the real value (once resolved)
-    - returns a safe placeholder value
-
-- **Promise compatibility**  
-  Accessing `.then(...)` forwards to the underlying deferred promise, allowing async usage.
-
-- **Late data injection**  
-  Once the real recommendation item is available, its data is copied into the proxy target object.
-
-This makes the transition from “unresolved” to “resolved” completely transparent.
-
----
-
-### Why This Works Across Frameworks
-
-This approach ensures that:
-
-- the same core logic works for React and non-React frameworks
-- recommendation items can be read synchronously
-- async resolution integrates naturally with effects and lifecycle hooks
-- internal SDK boundaries remain intact
-- static backend state is shared correctly
-
-No framework-specific logic is required in the core SDK.
-
----
-
-## React Integration Helpers
-
-The SDK provides a small React-specific helper layer to integrate recommendations into React applications while preserving the SDK’s internal async model and shared state.
-
-This layer is intentionally thin and does **not** reimplement SDK logic. It only adapts existing SDK primitives to React’s rendering and lifecycle model.
-
----
-
-### `FroomleSdkInit`
-
-`FroomleSdkInit` is a lightweight initialization component.
-
-Its responsibility is to trigger the resolution of pending recommendation requests once the React application is mounted.
-
-Key characteristics:
-
-- Calls `fulfillRecommendations()` exactly once on mount
-- Ensures all queued recommendation requests are executed
-- Does not render anything itself
-- Acts purely as a lifecycle hook
-
-This component should be mounted near the root of the React tree.
-
----
-
-### `useNewCreateReco`
-
-`useNewCreateReco` is a React hook that requests a single recommendation and binds it to component state.
-
-It bridges three concerns:
-
-- the SDK’s promise-like recommendation model
-- React’s render cycle
-- referential stability across renders
-
----
-
-### Hook Behavior
-
-The hook works as follows:
-
-1. A recommendation request is created once using `proxyReco(req)`
-2. The result is stored in a `ref` to ensure it is not recreated on re-renders
-3. A `then(...)` callback is registered to detect when the recommendation resolves
-4. When resolved, the hook forces a component update
-5. The resolved `RecommendationItem` is returned
-
-This allows React components to render immediately and update automatically once recommendation data becomes available.
-
----
-
-### Why `useRef` Is Used
-
-`useRef` is used instead of `useState` to ensure that:
-
-- the recommendation request is created only once
-- no duplicate requests are triggered
-- static SDK state remains consistent
-- React re-renders do not affect request identity
-
-This is critical because the SDK relies on shared internal state.
-
----
-
-If you want next, I can:
-- add a **usage example** section
-- document `proxyReco` explicitly
-- or explain how multiple hooks coordinate through `fulfillRecommendations()`
-
-## JavaScript Modules
-
-The SDK ships multiple JavaScript modules, including:
-
-- a **default JavaScript module**
-- a **React-specific module**
-- **( potentially more modules in the future )**
-
-Both modules are distributed together but serve different integration use cases.
-
----
-
-### Background Problem
-
-Originally, the default JavaScript module and the React module were **compiled separately**.
-
-However, the React module depended on internal logic that was also used by the default module. Because both modules were built independently, this resulted in:
-
-- the **same internal code being compiled twice**
-- **separate static instances** of internal classes
-- shared state (for example backend state or configuration) no longer being shared
-
-This caused incorrect behavior, as the SDK relies on **single, shared static state** across the entire runtime.
-
----
-
-### Why Not Just Re-Export Everything
-
-Exposing all internal logic from the default module was not an option because:
-
-- not all internal classes are part of the public API
-- many classes must remain hidden to prevent incorrect usage
-- exposing everything would break the SDK’s API boundaries
-
-The React module needed access to internal functionality **without making that functionality public**.
-
----
-
-### Solution: Shared Module Chunk
-
-To solve this, the JavaScript builds are structured so that:
-
-- shared internal code is compiled **once**
-- both the default module and the React module depend on the **same compiled chunk**
-- static state is shared correctly at runtime
-
-This is achieved by compiling the modules together and extracting shared code into a **common chunk**, which both modules import.
-
----
-
-### Resulting Behavior
-
-With this setup:
-
-- internal singletons and static state exist only once
-- the default module and React module remain logically separate
-- API boundaries are preserved
-- users can import only what is intended to be public
-- internal code reuse is safe and consistent
-
-From the user’s perspective, the modules behave independently, while internally they share the same core implementation.
-
----
-
-## Supporting a New Framework
-
-The SDK is designed so that **adding support for a new frontend framework does not require changes to the core logic**. Instead, framework support is implemented as a thin adaptation layer on top of the existing primitives.
-
-This section describes what is required to integrate a new framework.
-
----
-
-### Core Principles
-
-When adding a new framework integration, the following principles must be preserved:
-
-- **Single shared SDK state**  
-  All framework integrations must share the same internal static state (backend, requests, configuration).
-
-- **Deferred recommendation resolution**  
-  Recommendation requests are created early and resolved later in a batched backend call.
-
-- **No direct backend access**  
-  Framework layers must never call backend logic directly. They rely on existing SDK functions.
-
-- **No expansion of the public API**  
-  Internal classes remain internal; the framework layer adapts behavior, not visibility.
-
----
-
-### Required Building Blocks
-
-A framework integration typically needs the following pieces.
-
-#### 1. A Stable Recommendation Handle
-
-The framework must receive a value that:
-
-- can be accessed synchronously during render
-- is referentially stable across renders
-- updates automatically once data becomes available
-
-This is achieved by using the existing **proxy-based recommendation item**, which behaves as both:
-
-- a `RecommendationItem`
-- a `PromiseLike<RecommendationItem>`
-
-New frameworks should reuse this mechanism rather than reimplementing it.
-
----
-
-#### 2. Deferred Request Registration
-
-The framework layer must:
-
-- create recommendation requests using the shared request queue
-- avoid triggering backend requests immediately
-- rely on deferred resolution
-
-This ensures that:
-
-- requests can be batched
-- ordering is preserved
-- backend calls remain predictable
-
----
-#### 3. A Lifecycle Hook to Fulfill Requests
-
-Every framework must provide **one well-defined moment** where pending recommendation requests are fulfilled.
-
-This usually maps to:
-
-- an application mount hook
-- a root-level lifecycle event
-- a global effect or initialization step
-
-At this point, the framework integration must call:
-
-- `fulfillRecommendations()`
-
-This triggers the backend request and resolves all pending recommendation proxies.
-
----
-
-##### How This SDK Does It
-
-In this SDK, recommendation requests are **created lazily** during component or template execution, but they are **not fulfilled immediately**.
-
-Instead:
-
-- all recommendation requests are collected in a shared queue
-- the framework integration defines a single initialization point
-- at that point, `fulfillRecommendations()` is called once
-
-For example:
-
-- in React, this is done via a small root-level initialization component
-- the call is placed inside a mount effect
-- this ensures all components have had a chance to register their requests first
-
-This approach guarantees that:
-
-- all requests are batched into a single backend call
-- request order is preserved
-- static SDK state is shared correctly
-- framework rendering remains predictable
-
-The same pattern can be applied to any other framework by choosing an appropriate lifecycle boundary and invoking `fulfillRecommendations()` exactly once per render cycle or application start.
-
-
-#### 4. Controlled Re-render or Update Trigger
-
-Once a recommendation resolves, the framework must:
-
-- trigger a re-render
-- or notify the framework’s change detection system
-
-How this is done depends on the framework:
-
-- React: `useEffect` + state update
-- Vue: reactive ref update
-- Svelte: store or reactive assignment
-- Others: equivalent lifecycle or observer mechanism
-
-The SDK itself does **not** trigger renders; this is the responsibility of the framework adapter.
-
----
-
-### What You Do *Not* Need
-
-When supporting a new framework, you do **not** need to:
-
-- modify `RecoBackendV2`
-- modify DOM logic (`DomDomDom`, `FroomleDomTree`, `DomNode`)
-- introduce framework-specific logic into the core SDK
-- expose additional internal classes
-
-The framework layer is purely an adapter.
-
----
-
-### Minimal Integration Checklist
-
-To support a new framework, you need:
-
-- a wrapper that calls `proxyReco(...)`
-- a place to call `fulfillRecommendations()`
-- a mechanism to trigger framework updates on resolution
-- no changes to core SDK internals
-
-If these conditions are met, the framework will integrate correctly.
-
----
+https://docs.froomle.ai/froomle-doc-main/v2/js_lib/jslib.html