@hashtagcms/web-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 HashtagCMS
+
+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,71 @@
+# @hashtagcms/web-sdk
+
+> Core JavaScript SDK for the HashtagCMS ecosystem
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+This package contains the core JavaScript logic and components for HashtagCMS, providing shared functionality that is used across both **Blade/PHP** (`@hashtagcms/web-ui-kit`) and **Java** (`@hashtagcms/theme-java`) theme ecosystems.
+
+## 📚 Documentation
+
+For more detailed information, check the following guides:
+
+- [Architecture & Design](./docs/01-architecture.md)
+- [Bootstrap & Global Config](./docs/02-bootstrap.md)
+- [Component API Reference](./docs/03-components.md)
+- [Integrating with Themes (PHP/Java)](./docs/04-integration.md)
+
+## ✨ Features
+
+- 🛠️ **Core Components** - Shared logic like Configuration forms and Analytics tracking
+- 🔧 **Configurable** - Manage application settings with `AppConfig`
+- 🌐 **Standardized Requests** - Automatic CSRF token handling and Axios configuration
+- 📦 **Framework Agnostic** - Vanilla JavaScript logic that works anywhere
+- 🚀 **Lightweight** - Minimized footprint for high-performance builds
+
+## 📦 Installation
+
+```bash
+npm install @hashtagcms/web-sdk
+```
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```javascript
+import { Analytics, Subscribe, AppConfig } from "@hashtagcms/web-sdk";
+
+// Initialize Components
+const subscribe = new Subscribe();
+const analytics = new Analytics();
+const config = new AppConfig({
+    media: { http_path: "https://cdn.example.com" }
+});
+
+// Use analytics
+analytics.trackPageView('/home');
+```
+
+## 🛠️ API Reference
+
+### `Subscribe`
+Handles newsletter or contact form configuration.
+- `init()`: Automatically finds form elements and attaches listeners.
+- `subscribeNow()`: Programmatically triggers a configuration request.
+
+### `Analytics`
+Standardized tracking for HashtagCMS.
+- `init(data)`: Initializes tracking with initial data.
+- `trackPageView(url)`: Tracks a page view event.
+- `trackEventView(category, action, value)`: Tracks a custom interaction.
+
+### `AppConfig`
+A helper class to manage CMS configuration.
+- `setConfigData(data)`: Update the current configuration.
+- `getValue(key, defaultVal)`: Safely retrieve configuration values.
+- `getMedia(path)`: Get the full CDN/Server path for a media asset.
+
+## 📄 License
+
+[MIT](LICENSE) © HashtagCMS

package/docs/01-architecture.md

@@ -0,0 +1,27 @@
+# Web SDK Architecture
+
+The `@hashtagcms/web-sdk` is designed as a lightweight, framework-agnostic collection of utilities and components used by the HashtagCMS ecosystem.
+
+## 📁 Project Structure
+
+```
+@hashtagcms/web-sdk/
+├── src/
+│   ├── bootstrap.js       # Global initialization (Axios, CSRF)
+│   ├── index.js           # Main entry point (Exports)
+│   ├── components/        # UI-related logic
+│   │   └── subscribe.js   # Configuration form handler
+│   ├── helpers/           # Shared helpers
+│   │   └── common.js      # AppConfig and utilities
+│   └── utils/             # General utilities
+│       └── analytics.js   # Tracking logic
+├── package.json
+└── README.md
+```
+
+## 🏗️ Design Principles
+
+1. **Framework Agnostic**: No dependency on React, Vue, or Angular. Uses vanilla JavaScript to ensure compatibility with any frontend environment (Blade templates, Thymeleaf, etc.).
+2. **Minimal Dependencies**: Keeps the bundle size small. Currently only depends on `axios` for HTTP requests.
+3. **Singleton Compatibility**: Designed to be initialized once per page load to manage global state like configuration and tracking.
+4. **Data-Attr Driven**: Components are designed to find their target elements using HTML5 `data-` attributes, reducing the need for explicit DOM passing in most cases.

package/docs/02-bootstrap.md

@@ -0,0 +1,32 @@
+# Bootstrap and Initialization
+
+The `bootstrap.js` file handles the global setup required for HashtagCMS to communicate with the backend.
+
+## 🛠️ Automated Setup
+
+When you import the SDK, it automatically performs several actions:
+
+1. **Axios Configuration**:
+   - Sets the `X-Requested-With: XMLHttpRequest` header.
+   - Enables `withCredentials` for cross-site cookie handling.
+2. **CSRF Protection**:
+   - Automatically looks for a `<meta name="csrf-token" content="...">` tag in the document head.
+   - Sets the `X-CSRF-TOKEN` header for all Axios requests.
+   - Sets the `Authorization: Bearer <token>` header for API compatibility.
+
+## 🚀 Manual Usage
+
+In most cases, you don't need to call bootstrap manually. It is executed as a side-effect when you import the main SDK index or components.
+
+```javascript
+// This will trigger bootstrap.js
+import { Subscribe } from '@hashtagcms/web-sdk';
+```
+
+## 🌐 Global Axios
+
+The SDK exposes `axios` to the global `window` object for convenience in legacy scripts or simple inline templates:
+
+```javascript
+window.axios.get('/api/endpoint').then(...);
+```

package/docs/03-components.md

@@ -0,0 +1,62 @@
+# Component Documentation
+
+## `Newsletter`
+
+Handles newsletter and subscription forms using a standardized HTML structure. 
+*Note: Also exported as `Subscribe` for backward compatibility.*
+
+### Usage
+```javascript
+import { Newsletter } from '@hashtagcms/web-sdk';
+const newsletter = new Newsletter();
+```
+
+### HTML Requirements
+The component automatically detects if it should use the new `newsletter` or legacy `subscribe` selectors.
+
+**Primary (New):**
+- `form[data-form='newsletter-form']`
+- `span[data-class='newsletter-message']`
+- `div[data-message-holder='newsletter-message-holder']`
+- `span[data-class='newsletter-close']`
+
+**Legacy (Fallback):**
+- `form[data-form='subscribe-form']`
+- `span[data-class='subscribe-message']`
+- `div[data-message-holder='subscribe-message-holder']`
+- `span[data-class='subscribe-close']`
+
+---
+
+## `Analytics`
+
+Provides a unified interface for tracking page views and custom events.
+
+### Methods
+- `init(data)`: Optional initialization with default data.
+- `trackPageView(url)`: Sends a page view event to the CMS and Google Analytics (if detected).
+- `trackEventView(category, action, value)`: Tracks custom interactions.
+
+### Example
+```javascript
+const analytics = new Analytics();
+analytics.trackPageView(window.location.pathname);
+```
+
+---
+
+## `AppConfig`
+
+Manages configuration data provided by the CMS backend.
+
+### Methods
+- `constructor(initialData)`
+- `setConfigData(data)`: Replace the current configuration.
+- `getValue(key, defaultVal)`: Safely retrieve a value (e.g., `getValue('site_name', 'Default Name')`).
+- `getMedia(path)`: Constructs a full URL for a media asset using the configured media HTTP path.
+
+### Example
+```javascript
+const config = new AppConfig(window.cmsConfig);
+const logoUrl = config.getMedia('logo.png');
+```

package/docs/04-integration.md

@@ -0,0 +1,39 @@
+# Theme Integration Guide
+
+The Web SDK isdesigned to be the functional core for any HashtagCMS theme, regardless of the rendering engine.
+
+## 🐘 PHP/Blade Integration (`@hashtagcms/web-ui-kit`)
+
+In a Laravel environment, themes typically use standard bundlers like Webpack or Vite. 
+
+1. Install the SDK: `npm install @hashtagcms/web-sdk`
+2. Import in your `app.js`:
+```javascript
+import { Subscribe, Analytics, AppConfig } from '@hashtagcms/web-sdk';
+
+window.HashtagCms = {
+    Subscribe: new Subscribe(),
+    Analytics: new Analytics(),
+    AppConfig: new AppConfig(window.cmsData)
+};
+```
+
+## ☕ Java/Thymeleaf Integration (`@hashtagcms/theme-java`)
+
+In the Java ecosystem, the SDK can be integrated via NPM (if using a modern JS build pipeline) or by including the bundled distribution in your templates.
+
+1. Ensure the `csrf-token` meta tag is populated by the Java backend.
+2. Initialize the SDK in your main template:
+```html
+<script th:inline="javascript">
+    /* Initialize config from server-side model */
+    const config = new HashtagCms.AppConfig([[${cmsConfig}]]);
+</script>
+```
+
+## 🏗️ Future Platforms
+
+Because the SDK is vanilla Javascript and focused on API interactions, it can be easily ported to:
+- Mobile web views.
+- Headless CMS frontends (Next.js, Nuxt.js).
+- Static site generators.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@hashtagcms/web-sdk",
+  "version": "1.0.0",
+  "description": "Core SDK for HashtagCMS Frontend",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "webpack --mode production"
+  },
+  "author": "HashtagCMS",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.8.0"
+  },
+  "devDependencies": {
+    "webpack": "^5.104.1",
+    "webpack-cli": "^6.0.1"
+  }
+}

package/src/bootstrap.js

@@ -0,0 +1,11 @@
+import axios from "axios";
+axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
+let token = document.head.querySelector('meta[name="csrf-token"]');
+if (token) {
+    axios.defaults.headers.common['X-CSRF-TOKEN'] = token.content;
+    axios.defaults.headers.common['Authorization'] = 'Bearer '+token.content;
+    axios.defaults.withCredentials = true;
+} else {
+    // console.error('CSRF token not found: https://laravel.com/docs/csrf#csrf-x-csrf-token');
+}
+window.axios = axios;

package/src/components/newsletter.js

@@ -0,0 +1,75 @@
+export default class Newsletter {
+    constructor() {
+        this.elements = {
+            close: "span[data-class='newsletter-close']",
+            message: "span[data-class='newsletter-message']", 
+            form: "form[data-form='newsletter-form']",
+            messageHolder: "div[data-message-holder='newsletter-message-holder']"
+        };
+        
+        // Backward compatibility: Use 'subscribe' selectors if 'newsletter' form is not found
+        if (!document.querySelector(this.elements.form)) {
+             this.elements = {
+                close: "span[data-class='subscribe-close']",
+                message: "span[data-class='subscribe-message']", 
+                form: "form[data-form='subscribe-form']",
+                messageHolder: "div[data-message-holder='subscribe-message-holder']"
+            };
+        }
+
+        this.init();
+    }
+
+    init() {
+
+        if (document.querySelector(this.elements.close)) {
+            document.querySelector(this.elements.close).addEventListener('click', (ele) => {
+                document.querySelector(this.elements.messageHolder).style.display = "none";
+            });
+        }
+    }
+
+    newsletterNow() {
+        let showMessage = function (message) {
+            document.querySelector($this.elements.message).innerText = message;
+        }
+        let $this = this;
+        let afterSave = function (data) {
+            console.log("data ", data);
+            document.querySelector($this.elements.messageHolder).style.display = "";
+            if (data.success == true) {
+                showMessage(data.message);
+                document.querySelector($this.elements.message).innerText = data.message;
+                document.querySelector($this.elements.form + " input[type='email']").value = '';
+                document.querySelector($this.elements.message).classList.remove("text-danger");
+                document.querySelector($this.elements.message).classList.add("text-success");
+            } else {
+                let errorMsg = (data.message && data.message.email && data.message.email[0]) ? data.message.email[0] : (data.message || "There is some error.");
+                showMessage(errorMsg);
+                document.querySelector($this.elements.message).classList.remove("text-success");
+                document.querySelector($this.elements.message).classList.add("text-danger");
+            }
+        }
+
+        let email = document.querySelector(this.elements.form + " input[type='email']");
+        let url = "/common/newsletter";
+        let data = { email: email.value };
+        axios.post(url, data)
+            .then(response => {
+                afterSave(response.data);
+            }).catch((error) => {
+                afterSave(error.response.data);
+            });
+
+        return false;
+    }
+
+    /**
+     * Alias for newsletterNow
+     * @deprecated
+     */
+    subscribeNow() {
+        return this.newsletterNow();
+    }
+
+}

package/src/helpers/common.js

@@ -0,0 +1,18 @@
+export class AppConfig {
+    constructor(data) {
+        this.configData = data;
+    }
+
+    setConfigData(data) {
+        this.configData = data;
+    }
+
+    getValue(key, defaultVal) {
+        return this.configData[key] || defaultVal;
+    }
+
+    getMedia(path) {
+        let media = this.getValue("media");
+        return media.http_path+"/"+path;
+    }
+};

package/src/index.js

@@ -0,0 +1,11 @@
+import './bootstrap';
+import Newsletter from './components/newsletter';
+import Analytics from './utils/analytics';
+import { AppConfig } from './helpers/common';
+
+export {
+    Newsletter,
+    Newsletter as Subscribe, // Alias for backward compatibility
+    Analytics,
+    AppConfig
+};

package/src/utils/analytics.js

@@ -0,0 +1,85 @@
+export default class Analytics {
+
+    constructor() {
+
+    }
+
+    init(data) {
+        this.readCounter(data);
+    }
+    readCounter(data) {
+
+        this.submit("post", "/analytics/publish", data);
+    }
+
+    /**
+     * Submit request.
+     *
+     * @param {string} requestType
+     * @param {string} url
+     * @param data
+     */
+    submit(requestType, url, data) {
+        /*data = new Blob([JSON.stringify(data)], {type : 'application/json'});
+        data.csrfToken = window.Laravel.csrfToken;
+        console.log("data",data);
+        navigator.sendBeacon(url, data);*/
+        return new Promise((resolve, reject) => {
+            axios[requestType](url, data)
+                .then(response => {
+                    resolve(response.data);
+                }).catch(error => {
+                    reject(error.response.data);
+            });
+        });
+    }
+
+    trackEventView (category, action ,value, cb) {
+        try {
+            //very very old ga
+            _gaq.push(['_trackEvent', category, action, value]);
+        } catch(e) {
+        }
+        if ( typeof ga != "undefined") {
+            try {
+                ga('send', {
+                    hitType : 'event',
+                    eventCategory : category,
+                    eventAction : action,
+                    eventLabel : value
+                });
+            } catch(e) {
+            }
+        }
+        if (cb) {
+            cb.apply(this, arguments);
+        }
+    }
+
+    /**
+     * Track Page view
+     * @param value
+     * @param cb
+     */
+    trackPageView (value, cb) {
+        try {
+            //Very very old ga
+            _gaq.push(['_trackPageview', value]);
+        } catch(e) {
+        }
+
+        if ( typeof ga != "undefined") {
+            try {
+                ga('send',
+                    {hitType: 'pageview',
+                        page: value
+                    });
+            } catch(e) {}
+        }
+
+        if (cb) {
+            cb.apply(this, arguments);
+        }
+    }
+
+}