@lynx-js/lynx-library-headers 0.0.1-alpha.4

package/include/lynx_resource_response.h

@@ -0,0 +1,63 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_LYNX_RESOURCE_RESPONSE_H_
+#define PLATFORM_EMBEDDER_PUBLIC_LYNX_RESOURCE_RESPONSE_H_
+
+#include "capi/lynx_resource_response_capi.h"
+
+namespace lynx {
+namespace pub {
+namespace resource {
+
+/**
+ * @apidoc
+ * @brief `LynxResourceResponse` is a class that represents a resource response.
+ */
+class LynxResourceResponse {
+ public:
+  explicit LynxResourceResponse(lynx_resource_response_t* response)
+      : response_(response) {}
+
+  ~LynxResourceResponse() { lynx_resource_response_release(response_); }
+
+  /**
+   * @apidoc
+   * @brief Set the code of the resource response.
+   * @param code The code of the resource response.
+   */
+  void SetCode(int code) { lynx_resource_response_set_code(response_, code); }
+
+  /**
+   * @apidoc
+   * @brief Set the error message of the resource response.
+   * @param msg The error message of the resource response.
+   */
+  void SetErrorMessage(const char* msg) {
+    lynx_resource_response_set_error_message(response_, msg);
+  }
+
+  /**
+   * @apidoc
+   * @brief Set the data of the resource response.
+   * @param content The data of the resource response.
+   * @param length The length of the data of the resource response.
+   * @param dtor The destructor of the data of the resource response.
+   * @param opaque The opaque data of the resource response.
+   */
+  void SetData(uint8_t* content, size_t length,
+               void (*dtor)(uint8_t*, size_t, void*) = nullptr,
+               void* opaque = nullptr) {
+    lynx_resource_response_set_data(response_, content, length, dtor, opaque);
+  }
+
+  void Complete() { lynx_resource_response_callback(response_); }
+
+ private:
+  lynx_resource_response_t* response_;
+};
+}  // namespace resource
+}  // namespace pub
+}  // namespace lynx
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_LYNX_RESOURCE_RESPONSE_H_

package/include/lynx_runtime_lifecycle_observer.h

@@ -0,0 +1,102 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_LYNX_RUNTIME_LIFECYCLE_OBSERVER_H_
+#define PLATFORM_EMBEDDER_PUBLIC_LYNX_RUNTIME_LIFECYCLE_OBSERVER_H_
+
+#include <memory>
+
+#include "capi/lynx_runtime_lifecycle_observer_capi.h"
+
+#ifdef USE_WEAK_SUFFIX_NAPI
+#include "third_party/weak-node-api/headers/weak_napi_defines.h"
+#endif
+
+namespace lynx {
+namespace pub {
+
+/**
+ * @apidoc
+ * @brief `LynxRuntimeLifecycleObserver` is the observer class for the
+ * lifecycle events of the Lynx runtime.
+ */
+class LynxRuntimeLifecycleObserver
+    : public std::enable_shared_from_this<LynxRuntimeLifecycleObserver> {
+ public:
+  LynxRuntimeLifecycleObserver() = default;
+  virtual ~LynxRuntimeLifecycleObserver() {
+    if (observer_) {
+      lynx_runtime_lifecycle_observer_release(observer_);
+    }
+  }
+
+  void InitIfNeeded() {
+    if (observer_) {
+      return;
+    }
+    // Hold a weak pointer.
+    observer_ = lynx_runtime_lifecycle_observer_create_with_finalizer(
+        new std::weak_ptr<LynxRuntimeLifecycleObserver>(weak_from_this()),
+        [](lynx_runtime_lifecycle_observer_t*, void* user_data) {
+          std::weak_ptr<LynxRuntimeLifecycleObserver>* weak_ptr =
+              reinterpret_cast<std::weak_ptr<LynxRuntimeLifecycleObserver>*>(
+                  user_data);
+          delete weak_ptr;
+        });
+
+    lynx_runtime_lifecycle_observer_bind_attach_callback(
+        observer_,
+        [](lynx_runtime_lifecycle_observer_t* observer, napi_env env) {
+          std::weak_ptr<LynxRuntimeLifecycleObserver>* weak_ptr =
+              reinterpret_cast<std::weak_ptr<LynxRuntimeLifecycleObserver>*>(
+                  lynx_runtime_lifecycle_observer_get_user_data(observer));
+          std::shared_ptr<LynxRuntimeLifecycleObserver> shared_observer =
+              weak_ptr ? weak_ptr->lock() : nullptr;
+          if (shared_observer) {
+            shared_observer->OnRuntimeAttach(env);
+          }
+        });
+    lynx_runtime_lifecycle_observer_bind_detach_callback(
+        observer_, [](lynx_runtime_lifecycle_observer_t* observer) {
+          std::weak_ptr<LynxRuntimeLifecycleObserver>* weak_ptr =
+              reinterpret_cast<std::weak_ptr<LynxRuntimeLifecycleObserver>*>(
+                  lynx_runtime_lifecycle_observer_get_user_data(observer));
+          std::shared_ptr<LynxRuntimeLifecycleObserver> shared_observer =
+              weak_ptr ? weak_ptr->lock() : nullptr;
+          if (shared_observer) {
+            shared_observer->OnRuntimeDetach();
+          }
+        });
+  }
+
+  /**
+   * @apidoc
+   * @brief Callback function invoked when the runtime is attached.
+   * Derived classes can override this method to perform custom operations
+   * when the runtime attaches.
+   * @param env The Napi environment.
+   */
+  virtual void OnRuntimeAttach(napi_env env) {}
+
+  /**
+   * @apidoc
+   * @brief Callback function invoked when the runtime is detached.
+   * Derived classes can override this method to perform custom cleanup
+   * operations when the runtime detaches.
+   */
+  virtual void OnRuntimeDetach() {}
+
+  lynx_runtime_lifecycle_observer_t* Impl() { return observer_; }
+
+ private:
+  lynx_runtime_lifecycle_observer_t* observer_ = nullptr;
+};
+
+}  // namespace pub
+}  // namespace lynx
+
+#ifdef USE_WEAK_SUFFIX_NAPI
+#include "third_party/weak-node-api/headers/weak_napi_undefs.h"
+#endif
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_LYNX_RUNTIME_LIFECYCLE_OBSERVER_H_

package/include/lynx_security_service.h

@@ -0,0 +1,78 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_LYNX_SECURITY_SERVICE_H_
+#define PLATFORM_EMBEDDER_PUBLIC_LYNX_SECURITY_SERVICE_H_
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "capi/lynx_security_service_capi.h"
+#include "capi/lynx_service_center_capi.h"
+#include "lynx_service_center.h"
+
+namespace lynx {
+namespace pub {
+
+class LynxSecurityService
+    : public LynxServiceBase,
+      public std::enable_shared_from_this<LynxSecurityService> {
+ public:
+  LynxSecurityService() = default;
+  ~LynxSecurityService() = default;
+
+  void InitIfNeeded() override {
+    if (security_service_) {
+      return;
+    }
+    security_service_ = lynx_security_service_create_with_finalizer(
+        new std::weak_ptr<LynxSecurityService>(weak_from_this()),
+        [](lynx_security_service_t* security_service, void* user_data) {
+          std::weak_ptr<LynxSecurityService>* weak_ptr =
+              reinterpret_cast<std::weak_ptr<LynxSecurityService>*>(user_data);
+          delete weak_ptr;
+        });
+    lynx_security_service_bind(
+        security_service_, [](lynx_security_service_t* security_service,
+                              uint8_t* content, size_t length, const char* url,
+                              lynx_tasm_type_e type, const char** error_msg) {
+          std::weak_ptr<LynxSecurityService>* weak_ptr =
+              reinterpret_cast<std::weak_ptr<LynxSecurityService>*>(
+                  lynx_security_service_get_user_data(security_service));
+          std::shared_ptr<LynxSecurityService> shared_security_service =
+              weak_ptr ? weak_ptr->lock() : nullptr;
+          if (shared_security_service) {
+            return shared_security_service->VerifyTASM(content, length, url,
+                                                       type, error_msg);
+          }
+          return 0;
+        });
+  }
+
+  lynx_service_type_e GetServiceType() override { return kServiceTypeSecurity; }
+
+  void* Impl() override { return security_service_; }
+
+  /**
+   * @brief This function is designed to use specified verify logic to check the
+   * template consistency.
+   * @param content The TASM content to be checked.
+   * @param length The TASM content length.
+   * @param url The TASM content URL.
+   * @param type The TASM type.
+   * @param error_msg The error message.
+   * @return int The verification result.
+   */
+  virtual int VerifyTASM(uint8_t* content, size_t length, const char* url,
+                         lynx_tasm_type_e type, const char** error_msg) = 0;
+
+ private:
+  lynx_security_service_t* security_service_ = nullptr;
+};
+}  // namespace pub
+}  // namespace lynx
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_LYNX_SECURITY_SERVICE_H_

package/include/lynx_service_center.h

@@ -0,0 +1,64 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_LYNX_SERVICE_CENTER_H_
+#define PLATFORM_EMBEDDER_PUBLIC_LYNX_SERVICE_CENTER_H_
+
+#include <memory>
+#include <unordered_map>
+
+#include "capi/lynx_service_center_capi.h"
+
+namespace lynx {
+namespace pub {
+
+class LynxServiceBase {
+ public:
+  LynxServiceBase() = default;
+  virtual ~LynxServiceBase() = default;
+
+  virtual void InitIfNeeded() = 0;
+
+  virtual lynx_service_type_e GetServiceType() = 0;
+
+  virtual void* Impl() = 0;
+};
+
+/**
+ * @brief LynxServiceCenter is the service center of Lynx. It provides methods
+ * for registering services.
+ */
+class LynxServiceCenter {
+ public:
+  static LynxServiceCenter& GetInstance() {
+    static LynxServiceCenter instance;
+    return instance;
+  }
+
+  LynxServiceCenter(const LynxServiceCenter&) = delete;
+  LynxServiceCenter& operator=(const LynxServiceCenter&) = delete;
+
+  /**
+   * @brief RegisterService is used to register a service.
+   * @param service The service to be registered.
+   */
+  void RegisterService(std::shared_ptr<LynxServiceBase> service) {
+    service->InitIfNeeded();
+    lynx_service_register_service(service_center_, service->GetServiceType(),
+                                  service->Impl());
+    services_[service->GetServiceType()] = service;
+  }
+
+ private:
+  LynxServiceCenter() { service_center_ = lynx_service_get_center_instance(); }
+  ~LynxServiceCenter() = default;
+
+  lynx_service_center_t* service_center_ = nullptr;
+  std::unordered_map<lynx_service_type_e, std::shared_ptr<LynxServiceBase> >
+      services_;
+};
+
+}  // namespace pub
+}  // namespace lynx
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_LYNX_SERVICE_CENTER_H_

package/include/lynx_template_bundle.h

@@ -0,0 +1,65 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_LYNX_TEMPLATE_BUNDLE_H_
+#define PLATFORM_EMBEDDER_PUBLIC_LYNX_TEMPLATE_BUNDLE_H_
+
+#include <string>
+
+#include "capi/lynx_template_bundle_capi.h"
+
+namespace lynx {
+namespace pub {
+
+/**
+ * @apidoc
+ * @brief `TemplateBundle` is the output product of the PreDecode capability
+ * provided by the Lynx SDK. Client developers can parse the Lynx App Bundle
+ * product in advance to obtain the `TemplateBundle` object and consume the App
+ * Bundle product.
+ */
+class LynxTemplateBundle {
+ public:
+  LynxTemplateBundle(uint8_t* content, size_t size,
+                     void (*dtor)(uint8_t*, size_t, void*) = nullptr,
+                     void* opaque = nullptr)
+      : template_bundle_(
+            lynx_template_bundle_create(content, size, dtor, opaque)) {}
+
+  ~LynxTemplateBundle() { lynx_template_bundle_release(template_bundle_); }
+
+  /**
+   * @apidoc
+   * @brief Determines whether the current `TemplateBundle` object is valid.
+   * @return `true` if the current `TemplateBundle` object is valid, else
+   * `false`.
+   */
+  bool IsValid() const {
+    return lynx_template_bundle_is_valid(template_bundle_);
+  }
+
+  /**
+   * @apidoc
+   * @brief When `TemplateBundle` is an invalid object, use this method to
+   * obtain the exception information that occurred during template parsing
+   * @return The exception information.
+   */
+  std::string GetErrorMessage() {
+    const char* error_message =
+        lynx_template_bundle_get_error_message(template_bundle_);
+    return error_message ? std::string(error_message) : "";
+  }
+
+  lynx_template_bundle_t* Impl() { return template_bundle_; }
+
+  LynxTemplateBundle(const LynxTemplateBundle&) = delete;
+  LynxTemplateBundle& operator=(const LynxTemplateBundle&) = delete;
+
+ private:
+  lynx_template_bundle_t* template_bundle_;
+};
+
+}  // namespace pub
+}  // namespace lynx
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_LYNX_TEMPLATE_BUNDLE_H_

package/include/lynx_template_data.h

@@ -0,0 +1,104 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_LYNX_TEMPLATE_DATA_H_
+#define PLATFORM_EMBEDDER_PUBLIC_LYNX_TEMPLATE_DATA_H_
+
+#include <string>
+
+#include "capi/lynx_template_data_capi.h"
+
+namespace lynx {
+namespace pub {
+
+/**
+ * @apidoc
+ * @brief TemplateData is a data structure provided by Lynx. It is used to store
+ * the data types accepted by Lynx at runtime and can be constructed using
+ * either a string or a map type.
+ */
+class LynxTemplateData {
+ public:
+  /**
+   * @apidoc
+   * @brief Constructs a new LynxTemplateData object.
+   * @param json The JSON string used to create the template data.
+   */
+  explicit LynxTemplateData(const std::string& json)
+      : template_data_(lynx_template_data_create_from_json(json.c_str())) {}
+  ~LynxTemplateData() { lynx_template_data_release(template_data_); }
+
+  /**
+   * @apidoc
+   * @brief Update the current TemplateData with the JSON string.
+   * @param json The JSON string used to update the template data.
+   */
+  void UpdateWithJson(const std::string& json) {
+    if (read_only_) {
+      // If the data is read only, we can't update it.
+      return;
+    }
+    if (template_data_) {
+      lynx_template_data_release(template_data_);
+    }
+    template_data_ = lynx_template_data_create_from_json(json.c_str());
+    if (!processor_name_.empty()) {
+      lynx_template_data_mark_state(template_data_, processor_name_.c_str());
+    }
+  }
+
+  /**
+   * @apidoc
+   * @brief Mark the current TemplateData with the associated dataProcessor
+   * name.
+   * @param name Marked name.
+   */
+  void MarkState(const std::string& name) {
+    processor_name_ = name;
+    lynx_template_data_mark_state(template_data_, name.c_str());
+  }
+
+  /**
+   * @apidoc
+   * @brief Mark the current TemplateData as read-only. TemplateData will be
+   * sync to Native. For Thread-Safety, we will clone the value in Native Side.
+   * In some case, this may result in performance-loss, If your data won't
+   * change any more, Please call this method to mark value Read-Only, so we'll
+   * no longer clone the value any more to improve performance.
+   */
+  void MarkReadOnly() {
+    read_only_ = true;
+    lynx_template_data_set_read_only(template_data_, read_only_);
+  }
+
+  /**
+   * @apidoc
+   * @brief Check if the current TemplateData is read-only.
+   * @return True if the current TemplateData is read-only, false otherwise.
+   */
+  bool IsReadOnly() const { return read_only_; }
+
+  /**
+   * @apidoc
+   * @brief Get the name of the dataProcessor associated with the current
+   * TemplateData.
+   * @return The name of the dataProcessor associated with the current
+   * TemplateData.
+   */
+  std::string GetProcessorName() const { return processor_name_; }
+
+  lynx_template_data_t* Impl() { return template_data_; }
+
+  LynxTemplateData(const LynxTemplateData&) = delete;
+  LynxTemplateData& operator=(const LynxTemplateData&) = delete;
+
+ private:
+  lynx_template_data_t* template_data_;
+  std::string processor_name_;
+  bool read_only_ = false;
+};
+
+}  // namespace pub
+}  // namespace lynx
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_LYNX_TEMPLATE_DATA_H_

package/include/lynx_trail_service.h

@@ -0,0 +1,81 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_LYNX_TRAIL_SERVICE_H_
+#define PLATFORM_EMBEDDER_PUBLIC_LYNX_TRAIL_SERVICE_H_
+
+#include <memory>
+#include <optional>
+#include <string>
+
+#include "capi/lynx_service_center_capi.h"
+#include "capi/lynx_trail_service_capi.h"
+#include "lynx_service_center.h"
+
+namespace lynx {
+namespace pub {
+
+class LynxTrailService : public LynxServiceBase,
+                         public std::enable_shared_from_this<LynxTrailService> {
+ public:
+  LynxTrailService() = default;
+  ~LynxTrailService() override {
+    if (trail_service_) {
+      lynx_trail_service_release(trail_service_);
+      trail_service_ = nullptr;
+    }
+  }
+
+  void InitIfNeeded() override {
+    if (trail_service_) {
+      return;
+    }
+    // LynxTrailService must be owned by std::shared_ptr before InitIfNeeded()
+    // is called; otherwise weak_from_this() is empty and callbacks return null.
+    std::weak_ptr<LynxTrailService> self = weak_from_this();
+    trail_service_ = lynx_trail_service_create_with_finalizer(
+        new std::weak_ptr<LynxTrailService>(self),
+        [](lynx_trail_service_t* trail_service, void* user_data) {
+          std::weak_ptr<LynxTrailService>* weak_ptr =
+              reinterpret_cast<std::weak_ptr<LynxTrailService>*>(user_data);
+          delete weak_ptr;
+        });
+    lynx_trail_service_bind(
+        trail_service_,
+        [](lynx_trail_service_t* trail_service, const char* key) {
+          std::weak_ptr<LynxTrailService>* weak_ptr =
+              reinterpret_cast<std::weak_ptr<LynxTrailService>*>(
+                  lynx_trail_service_get_user_data(trail_service));
+          std::shared_ptr<LynxTrailService> shared_trail_service =
+              weak_ptr ? weak_ptr->lock() : nullptr;
+          if (!shared_trail_service) {
+            return static_cast<const char*>(nullptr);
+          }
+          std::optional<std::string> value =
+              shared_trail_service->GetStringValueForTrailKey(key ? key : "");
+          if (!value) {
+            return static_cast<const char*>(nullptr);
+          }
+          // The returned pointer is valid until the next callback on the same
+          // thread. Callers must copy it immediately.
+          static thread_local std::string result;
+          result = *value;
+          return result.c_str();
+        });
+  }
+
+  lynx_service_type_e GetServiceType() override { return kServiceTypeTrail; }
+
+  void* Impl() override { return trail_service_; }
+
+  virtual std::optional<std::string> GetStringValueForTrailKey(
+      const std::string& key) = 0;
+
+ private:
+  lynx_trail_service_t* trail_service_ = nullptr;
+};
+
+}  // namespace pub
+}  // namespace lynx
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_LYNX_TRAIL_SERVICE_H_

package/include/lynx_update_meta.h

@@ -0,0 +1,56 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_LYNX_UPDATE_META_H_
+#define PLATFORM_EMBEDDER_PUBLIC_LYNX_UPDATE_META_H_
+
+#include <memory>
+
+#include "capi/lynx_update_meta_capi.h"
+#include "lynx_template_data.h"
+
+namespace lynx {
+namespace pub {
+
+/**
+ * @apidoc
+ * @brief LynxUpdateMeta is the update meta of Lynx. It provides methods for
+ * setting update data and global props.
+ */
+class LynxUpdateMeta {
+ public:
+  LynxUpdateMeta() : update_meta_(lynx_update_meta_create()) {}
+
+  ~LynxUpdateMeta() { lynx_update_meta_release(update_meta_); }
+
+  /**
+   * @apidoc
+   * @brief Set the update data of the current LynxUpdateMeta.
+   * @param data The update data to be set.
+   */
+  void SetUpdateData(std::shared_ptr<LynxTemplateData> data) {
+    lynx_update_meta_set_update_data(update_meta_, data->Impl());
+  }
+
+  /**
+   * @apidoc
+   * @brief Set the global props of the current LynxUpdateMeta.
+   * @param global_props The global props to be set.
+   */
+  void SetGlobalProps(std::shared_ptr<LynxTemplateData> global_props) {
+    lynx_update_meta_set_global_props(update_meta_, global_props->Impl());
+  }
+
+  lynx_update_meta_t* Impl() { return update_meta_; }
+
+  LynxUpdateMeta(const LynxUpdateMeta&) = delete;
+  LynxUpdateMeta& operator=(const LynxUpdateMeta&) = delete;
+
+ private:
+  lynx_update_meta_t* update_meta_;
+};
+
+}  // namespace pub
+}  // namespace lynx
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_LYNX_UPDATE_META_H_