VersaCommerce JavaScript SDK

Frontend JavaScript SDK for VersaCommerce shops that allows you to access products, collections, pages, blogs, navigation, and carts from any website.

Purpose: AI Agent Integration

This SDK serves as the "eyes and hands" for AI agents (like Claude) that can automatically build and customize online shops.

┌─────────────────┐         ┌─────────────┐         ┌─────────────────┐
│   AI Agent      │  ───►   │   JS-SDK    │  ───►   │  VersaCommerce  │
│   (Claude)      │         │  (this lib) │         │     Shop API    │
│                 │  ◄───   │             │  ◄───   │                 │
│ "Build theme"   │  data   │ getShop()   │  JSON   │  /js-api/*.json │
│                 │         │ getProducts │         │                 │
└─────────────────┘         └─────────────┘         └─────────────────┘

The AI agent uses SDK to:

• Read shop structure (getShop())
• Get all products (getProducts())
• Get collections (getCollections())
• Get pages and navigation (getPages(), getLinklists())

Then the agent can:

• Automatically generate themes
• Build navigation based on real data
• Create product pages

The SDK works in the browser (not server-side), so API endpoints must have CORS headers.

Installation

npm install @versacommerce/versacommerce-js-sdk

Or via script tag:

<script src="https://unpkg.com/@versacommerce/versacommerce-js-sdk"></script>

Quick Start

import VersaCommerce from '@versacommerce/versacommerce-js-sdk';

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

Shop

client.getShop().then((shop) => {
  console.log(shop.name); // => "My Shop"
  console.log(shop.currency); // => "EUR"
  console.log(shop.productsCount); // => 15
  console.log(shop.collectionsCount); // => 9
});

Products

// Find by ID
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('my-product').then((product) => {
  console.log(product.title);
});

Collections

// 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

// 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);
  console.log(page.content); // HTML content
});

Blogs & Articles

// Get all blogs
client.getBlogs().then((blogs) => {
  blogs.forEach((blog) => console.log(blog.title));
});

// Find blog by handle
client.findBlog('news').then((blog) => {
  console.log(blog.title);
  console.log(blog.articlesCount);
});

// Find article
client.findArticle('news', 'my-article').then((article) => {
  console.log(article.title);
  console.log(article.author);
  console.log(article.publishedAt);
});

Linklists (Navigation)

// Get all navigation menus
client.getLinklists().then((linklists) => {
  linklists.forEach((nav) => console.log(nav.handle, nav.title));
});

// Find navigation by handle
client.findLinklist('main-menu').then((nav) => {
  console.log(nav.title);
  nav.rootLinks.forEach((link) => {
    console.log(link.title, link.url);
    // Nested sub-navigation
    link.children.forEach((child) => {
      console.log('  -', child.title, child.url);
    });
  });
});

Cart

// Get cart
client.getCart().then((cart) => {
  console.log(cart.totalPrice);
  cart.items.forEach((item) => console.log(item.title));
});

// Add item to cart
const product = await client.findProduct(123);
const cart = await client.getCart();
cart.addItem(product);

Caching

The SDK automatically caches fetched resources. Subsequent requests for the same resource return the cached version:

// First call fetches from server
await client.findProduct(123);

// Second call returns cached version (no network request)
await client.findProduct(123);

Contributing

See DEVELOPMENT.md for development setup and guidelines.

License

MIT - see LICENSE