@versacommerce/versacommerce-js-sdk 0.5.0 → 0.5.2

package/README.md

@@ -2,45 +2,34 @@
 
 Frontend JavaScript SDK for VersaCommerce shops that allows you to access products, collections, pages, blogs, navigation, and carts from any website.
 
-## Example Usage
+## Installation
 
-```javascript
-const client = VersaCommerce.createClient({
-  shopName: 'mein-test-shop' // subdomain of your shop
-});
+```bash
+npm install @versacommerce/versacommerce-js-sdk
+```
 
-// 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/...'
-  });
-});
+Or via script tag:
 
-// 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/...'
-  });
-});
+```html
+<script src="https://unpkg.com/@versacommerce/versacommerce-js-sdk"></script>
+```
 
-// 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'
-});
+## Quick Start
 
-// find a product and add to cart
-Promise.all([client.findProduct('xyz1'), client.getCart()]).then((values) => {
-  const product = values[0];
-  const cart = values[1];
+```javascript
+import VersaCommerce from '@versacommerce/versacommerce-js-sdk';
 
-  cart.addItem(product);
+const client = VersaCommerce.createClient({
+  shopName: 'my-shop' // subdomain of your shop
 });
+
+// Fetch a product
+const product = await client.findProduct(123);
+console.log(product.title, product.price);
+
+// Add to cart
+const cart = await client.getCart();
+cart.addItem(product);
 ```
 
 ## API Reference
@@ -48,9 +37,8 @@ Promise.all([client.findProduct('xyz1'), client.getCart()]).then((values) => {
 ### Shop
 
 ```javascript
-// Get shop metadata
 client.getShop().then((shop) => {
-  console.log(shop.name); // => "Björn's Einkaufswelt"
+  console.log(shop.name); // => "My Shop"
   console.log(shop.currency); // => "EUR"
   console.log(shop.productsCount); // => 15
   console.log(shop.collectionsCount); // => 9
@@ -61,30 +49,43 @@ client.getShop().then((shop) => {
 
 ```javascript
 // Find by ID
-client.findProduct(206301).then((product) => { ... });
+client.findProduct(206301).then((product) => {
+  console.log(product.title);
+  console.log(product.price);
+  product.images.forEach((image) => {
+    console.log(image.resize(50, 50));
+  });
+});
 
 // Find by handle (URL slug)
-client.findProductByHandle('ball-in-vielen-farben').then((product) => {
-  console.log(product.title); // => "Ball"
+client.findProductByHandle('my-product').then((product) => {
+  console.log(product.title);
 });
 ```
 
 ### 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));
 });
+
+// Find by ID
+client.findCollection(20053).then((collection) => {
+  console.log(collection.title);
+  collection.products.forEach((product) => {
+    console.log(product.title);
+  });
+});
+
+// Find by handle
+client.findCollectionByHandle('sale').then((collection) => {
+  console.log(collection.title);
+});
 ```
 
-### Pages (CMS)
+### Pages
 
 ```javascript
 // Get all pages
@@ -94,8 +95,8 @@ client.getPages().then((pages) => {
 
 // Find page by handle
 client.findPage('impressum').then((page) => {
-  console.log(page.title); // => "Impressum"
-  console.log(page.content); // => "<h2>Verantwortlich</h2>..."
+  console.log(page.title);
+  console.log(page.content); // HTML content
 });
 ```
 
@@ -108,16 +109,16 @@ client.getBlogs().then((blogs) => {
 });
 
 // Find blog by handle
-client.findBlog('mein-blog').then((blog) => {
-  console.log(blog.title); // => "Mein Blog"
-  console.log(blog.articlesCount); // => 5
+client.findBlog('news').then((blog) => {
+  console.log(blog.title);
+  console.log(blog.articlesCount);
 });
 
 // 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"
+client.findArticle('news', 'my-article').then((article) => {
+  console.log(article.title);
+  console.log(article.author);
+  console.log(article.publishedAt);
 });
 ```
 
@@ -130,8 +131,8 @@ client.getLinklists().then((linklists) => {
 });
 
 // Find navigation by handle
-client.findLinklist('haupt-navigation').then((nav) => {
-  console.log(nav.title); // => "Haupt-Navigation"
+client.findLinklist('main-menu').then((nav) => {
+  console.log(nav.title);
   nav.rootLinks.forEach((link) => {
     console.log(link.title, link.url);
     // Nested sub-navigation
@@ -145,173 +146,33 @@ client.findLinklist('haupt-navigation').then((nav) => {
 ### Cart
 
 ```javascript
+// Get cart
 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
+// Add item to cart
+const product = await client.findProduct(123);
+const cart = await client.getCart();
+cart.addItem(product);
 ```
 
-## Installation
+## Caching
 
-```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
-```
+The SDK automatically caches fetched resources. Subsequent requests for the same resource return the cached version:
 
 ```javascript
-import VersaCommerce from '@versacommerce/versacommerce-js-sdk';
-
-const client = VersaCommerce.createClient({ shopName: 'my-shop' });
-```
+// First call fetches from server
+await client.findProduct(123);
 
-### 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>
+// Second call returns cached version (no network request)
+await client.findProduct(123);
 ```
 
-## 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
+## Contributing
 
-## 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
-```
+See [DEVELOPMENT.md](DEVELOPMENT.md) for development setup and guidelines.
 
 ## License