@versacommerce/versacommerce-js-sdk 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 VersaCommerce
+
+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,318 @@
+# VersaCommerce JavaScript SDK
+
+Frontend JavaScript SDK for VersaCommerce shops that allows you to access products, collections, pages, blogs, navigation, and carts from any website.
+
+## Example Usage
+
+```javascript
+const client = VersaCommerce.createClient({
+  shopName: 'mein-test-shop' // subdomain of your shop
+});
+
+// fetch a single product
+client.findProduct('xyz1').then((product) => {
+  console.log(product.title); // => 'Ein Beispielprodukt'
+  console.log(product.price); // => 5.95
+  product.images.forEach((image) => {
+    console.log(image.resize(50, 50));
+    // => 'http://img.versacommerce.io/...'
+  });
+});
+
+// fetch a single collection
+client.findCollection('xyz1').then((collection) => {
+  console.log(collection.title); // => 'Eine Beispielgruppe'
+  collection.products.forEach((product) => {
+    console.log(product.featuredImage.resize(50, 50));
+    // => 'http://img.versacommerce.io/...'
+  });
+});
+
+// fetch the same product again, but this time the product will be
+// retrieved from the local cache instead of firing another network request.
+client.findProduct('abc1').then((product) => {
+  console.log(product.title); // => 'Ein Beispielprodukt'
+});
+
+// find a product and add to cart
+Promise.all([client.findProduct('xyz1'), client.getCart()]).then((values) => {
+  const product = values[0];
+  const cart = values[1];
+
+  cart.addItem(product);
+});
+```
+
+## API Reference
+
+### Shop
+
+```javascript
+// Get shop metadata
+client.getShop().then((shop) => {
+  console.log(shop.name); // => "Björn's Einkaufswelt"
+  console.log(shop.currency); // => "EUR"
+  console.log(shop.productsCount); // => 15
+  console.log(shop.collectionsCount); // => 9
+});
+```
+
+### Products
+
+```javascript
+// Find by ID
+client.findProduct(206301).then((product) => { ... });
+
+// Find by handle (URL slug)
+client.findProductByHandle('ball-in-vielen-farben').then((product) => {
+  console.log(product.title); // => "Ball"
+});
+```
+
+### Collections
+
+```javascript
+// Find by ID
+client.findCollection(20053).then((collection) => { ... });
+
+// Find by handle
+client.findCollectionByHandle('sale').then((collection) => { ... });
+
+// Get all collections
+client.getCollections().then((collections) => {
+  collections.forEach((c) => console.log(c.title));
+});
+```
+
+### Pages (CMS)
+
+```javascript
+// Get all pages
+client.getPages().then((pages) => {
+  pages.forEach((page) => console.log(page.handle, page.title));
+});
+
+// Find page by handle
+client.findPage('impressum').then((page) => {
+  console.log(page.title); // => "Impressum"
+  console.log(page.content); // => "<h2>Verantwortlich</h2>..."
+});
+```
+
+### Blogs & Articles
+
+```javascript
+// Get all blogs
+client.getBlogs().then((blogs) => {
+  blogs.forEach((blog) => console.log(blog.title));
+});
+
+// Find blog by handle
+client.findBlog('mein-blog').then((blog) => {
+  console.log(blog.title); // => "Mein Blog"
+  console.log(blog.articlesCount); // => 5
+});
+
+// Find article
+client.findArticle('mein-blog', 'mein-artikel').then((article) => {
+  console.log(article.title); // => "Mein Artikel"
+  console.log(article.author); // => "Max Mustermann"
+  console.log(article.publishedAt); // => "2025-01-01T12:00:00+01:00"
+});
+```
+
+### Linklists (Navigation)
+
+```javascript
+// Get all navigation menus
+client.getLinklists().then((linklists) => {
+  linklists.forEach((nav) => console.log(nav.handle, nav.title));
+});
+
+// Find navigation by handle
+client.findLinklist('haupt-navigation').then((nav) => {
+  console.log(nav.title); // => "Haupt-Navigation"
+  nav.rootLinks.forEach((link) => {
+    console.log(link.title, link.url);
+    // Nested sub-navigation
+    link.children.forEach((child) => {
+      console.log('  -', child.title, child.url);
+    });
+  });
+});
+```
+
+### Cart
+
+```javascript
+client.getCart().then((cart) => {
+  console.log(cart.totalPrice);
+  cart.items.forEach((item) => console.log(item.title));
+});
+```
+
+## Tech Stack
+
+| Technology     | Version | Purpose               |
+| -------------- | ------- | --------------------- |
+| Node.js        | 22 LTS  | Runtime               |
+| Vite           | 6.x     | Build tool            |
+| Vitest         | 3.x     | Testing framework     |
+| ESLint         | 9.x     | Linting (Flat Config) |
+| Prettier       | 3.x     | Code formatting       |
+| GitHub Actions | -       | CI/CD                 |
+| npm            | -       | Package registry      |
+
+## Prerequisites
+
+- **Node.js 22** or higher (LTS recommended)
+- **npm** (comes with Node.js)
+
+```bash
+# Install Node.js via nvm (recommended)
+nvm install 22
+nvm use 22
+
+# Or use the .nvmrc file
+nvm use
+```
+
+## Installation
+
+```bash
+npm install
+```
+
+## Development
+
+```bash
+# Start development server
+npm run dev
+
+# Run tests in watch mode
+npm run test:watch
+
+# Check linting
+npm run lint
+
+# Format code
+npm run format
+```
+
+## Testing
+
+```bash
+# Run all tests
+npm run test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in browser mode
+npm run test:browser
+```
+
+### Test Results
+
+- **329 tests** across 39 test files
+- Unit tests for all core modules, models, and utilities
+- Integration tests for Store and Cart functionality
+
+## Building
+
+Creates a production build in `dist/`:
+
+```bash
+npm run build
+```
+
+### Build Output
+
+| File                           | Size     | Gzipped  |
+| ------------------------------ | -------- | -------- |
+| `versacommerce-js-sdk.umd.cjs` | 20.89 kB | 5.84 kB  |
+| `versacommerce-js-sdk.es.js`   | 62.24 kB | 11.89 kB |
+
+Both UMD (for `<script>` tags) and ES modules are generated with source maps.
+
+## Usage
+
+### Via npm
+
+```bash
+npm install @versacommerce/versacommerce-js-sdk
+```
+
+```javascript
+import VersaCommerce from '@versacommerce/versacommerce-js-sdk';
+
+const client = VersaCommerce.createClient({ shopName: 'my-shop' });
+```
+
+### Via Script Tag (UMD)
+
+For direct browser usage, include the UMD build from the `dist/` folder:
+
+```html
+<script src="path/to/versacommerce-js-sdk.umd.cjs"></script>
+<script>
+  const client = VersaCommerce.createClient({ shopName: 'my-shop' });
+</script>
+```
+
+## CI/CD
+
+The project uses **GitHub Actions** for continuous integration:
+
+- **CI Pipeline** (`.github/workflows/ci.yml`): Runs on every push and PR
+  - Linting with ESLint
+  - Format check with Prettier
+  - All tests with coverage
+  - Production build
+
+- **Publish Pipeline** (`.github/workflows/publish.yml`): Runs on release
+  - Publishes to npm
+
+## npm Scripts
+
+| Script                  | Description                    |
+| ----------------------- | ------------------------------ |
+| `npm run dev`           | Start Vite dev server          |
+| `npm run build`         | Production build               |
+| `npm run test`          | Run tests once                 |
+| `npm run test:watch`    | Run tests in watch mode        |
+| `npm run test:coverage` | Run tests with coverage report |
+| `npm run test:browser`  | Run tests in browser mode      |
+| `npm run lint`          | Check code with ESLint         |
+| `npm run lint:fix`      | Fix ESLint issues              |
+| `npm run format`        | Format code with Prettier      |
+| `npm run format:check`  | Check formatting               |
+
+## Project Structure
+
+```
+versacommerce-js-sdk/
+├── lib/                    # Source code
+│   ├── core/              # Core modules (Client, Adapter, Store, etc.)
+│   ├── models/            # Data models (Product, Cart, Variant, etc.)
+│   ├── utils/             # Utility functions
+│   ├── versacommerce.js   # Main entry point
+│   ├── exports.js         # Browser global export
+│   └── version.js         # Version number
+├── test/                   # Test files
+│   ├── unit/              # Unit tests
+│   ├── integration/       # Integration tests
+│   ├── support/           # Test helpers
+│   ├── fixtures/          # Test data
+│   └── setup.js           # Vitest setup
+├── dist/                   # Build output (generated)
+├── .github/workflows/      # GitHub Actions
+├── vite.config.js         # Vite configuration
+├── vitest.config.js       # Vitest configuration
+├── eslint.config.js       # ESLint 9 flat config
+└── .prettierrc            # Prettier configuration
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE)