@commercejs/nuxt 0.2.0

package/README.md

@@ -0,0 +1,99 @@
+# @commercejs/nuxt
+
+CommerceJS Nuxt module — composables, plugin, and auto-generated REST API.
+
+[![npm](https://img.shields.io/npm/v/@commercejs/nuxt?color=CB3837)](https://www.npmjs.com/package/@commercejs/nuxt)
+[![Nuxt](https://img.shields.io/badge/Nuxt-00DC82?logo=nuxt.js&logoColor=white)](https://nuxt.com/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+`@commercejs/nuxt` is a Nuxt module that integrates CommerceJS into your Nuxt application. It provides auto-imported composables, injects the adapter into your app context, and optionally generates a full REST API from your adapter — zero boilerplate.
+
+## Install
+
+```bash
+npm install @commercejs/nuxt @commercejs/types @commercejs/adapter-salla
+```
+
+## Setup
+
+Add the module to your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['@commercejs/nuxt'],
+
+  commerce: {
+    adapter: 'salla',       // adapter package to use
+    apiBase: '/api/_commerce', // REST API base path (default)
+    apiRoutes: true,         // auto-generate REST routes (default)
+  },
+})
+```
+
+## Usage
+
+### Composables
+
+The module auto-imports composables for your Vue components:
+
+```vue
+<script setup>
+const { data: products } = await useCommerce().getProducts({ limit: 12 })
+const { data: cart } = await useCommerce().getCart(cartId)
+</script>
+```
+
+### Plugin
+
+The adapter is available on `$commerce` in your Nuxt app:
+
+```typescript
+const { $commerce } = useNuxtApp()
+const store = await $commerce.getStore()
+```
+
+### Auto-Generated REST API
+
+When `apiRoutes` is enabled, the module registers 40+ REST endpoints:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/_commerce/products` | GET | List products |
+| `/api/_commerce/products/:id` | GET | Get product by ID |
+| `/api/_commerce/categories` | GET | List categories |
+| `/api/_commerce/cart` | POST | Create cart |
+| `/api/_commerce/cart/:id` | GET | Get cart |
+| `/api/_commerce/cart/:id/items` | POST | Add to cart |
+| `/api/_commerce/checkout/place-order` | POST | Place order |
+| `/api/_commerce/auth/login` | POST | Login |
+| `/api/_commerce/customer` | GET | Get customer profile |
+| `/api/_commerce/customer/orders` | GET | List orders |
+| `/api/_commerce/wishlist` | GET | Get wishlist |
+| `/api/_commerce/reviews/:productId` | GET | Get product reviews |
+| ... | ... | 30+ more routes |
+
+## Configuration
+
+```typescript
+interface CommerceModuleOptions {
+  /** Adapter name: 'salla', 'shopify', 'medusa', etc. */
+  adapter?: string
+
+  /** REST API base path (default: '/api/_commerce') */
+  apiBase?: string
+
+  /** Auto-generate REST API routes (default: true) */
+  apiRoutes?: boolean
+}
+```
+
+## Documentation
+
+Full docs at [commerce.js.org](https://commerce.js.org)
+
+## License
+
+[MIT](../../LICENSE)

package/dist/module.cjs

@@ -0,0 +1,5 @@
+module.exports = function(...args) {
+  return import('./module.mjs').then(m => m.default.call(this, ...args))
+}
+const _meta = module.exports.meta = require('./module.json')
+module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.mts

@@ -0,0 +1,23 @@
+import { NuxtModule } from '@nuxt/schema';
+
+interface CommerceModuleOptions {
+    /**
+     * The adapter to use (e.g., 'salla', 'zid', 'shopify', 'medusa').
+     * The adapter package must be installed separately.
+     */
+    adapter?: string;
+    /**
+     * Base path for auto-generated REST API routes.
+     * @default '/api/_commerce'
+     */
+    apiBase?: string;
+    /**
+     * Whether to register auto-generated REST API routes.
+     * @default true
+     */
+    apiRoutes?: boolean;
+}
+declare const commerceModule: NuxtModule<CommerceModuleOptions>;
+
+export { commerceModule as default };
+export type { CommerceModuleOptions };

package/dist/module.d.ts

@@ -0,0 +1,23 @@
+import { NuxtModule } from '@nuxt/schema';
+
+interface CommerceModuleOptions {
+    /**
+     * The adapter to use (e.g., 'salla', 'zid', 'shopify', 'medusa').
+     * The adapter package must be installed separately.
+     */
+    adapter?: string;
+    /**
+     * Base path for auto-generated REST API routes.
+     * @default '/api/_commerce'
+     */
+    apiBase?: string;
+    /**
+     * Whether to register auto-generated REST API routes.
+     * @default true
+     */
+    apiRoutes?: boolean;
+}
+declare const commerceModule: NuxtModule<CommerceModuleOptions>;
+
+export { commerceModule as default };
+export type { CommerceModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "@commercejs/nuxt",
+  "configKey": "commerce",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "0.2.0",
+  "builder": {
+    "@nuxt/module-builder": "0.8.4",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,101 @@
+import { defineNuxtModule, createResolver, addTypeTemplate, addPlugin, addServerPlugin, addImportsDir, addServerHandler } from '@nuxt/kit';
+import { consola } from 'consola';
+
+const logger = consola.withTag("@commercejs/nuxt");
+const commerceModule = defineNuxtModule({
+  meta: {
+    name: "@commercejs/nuxt",
+    configKey: "commerce",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  defaults: {
+    apiBase: "/api/_commerce",
+    apiRoutes: true
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    logger.info("Initializing CommerceJS module...");
+    nuxt.options.runtimeConfig.public.commerce = {
+      adapter: options.adapter || "",
+      apiBase: options.apiBase || "/api/_commerce"
+    };
+    addTypeTemplate({
+      filename: "types/commercejs.d.ts",
+      getContents: () => `
+        import type { CommerceAdapter } from '@commercejs/types'
+
+        declare module '#app' {
+          interface NuxtApp {
+            $commerce: CommerceAdapter
+          }
+        }
+
+        declare module 'vue' {
+          interface ComponentCustomProperties {
+            $commerce: CommerceAdapter
+          }
+        }
+
+        export {}
+      `
+    });
+    addPlugin(resolve("./runtime/plugin"));
+    addServerPlugin(resolve("./runtime/server/plugins/commerce-adapter"));
+    addImportsDir(resolve("./runtime/composables"));
+    if (options.apiRoutes) {
+      const apiBase = options.apiBase || "/api/_commerce";
+      let routeCount = 0;
+      const route = (path, handler, method) => {
+        addServerHandler({
+          route: `${apiBase}${path}`,
+          handler: resolve(`./runtime/server/api/${handler}`),
+          ...method ? { method } : {}
+        });
+        routeCount++;
+      };
+      route("/store", "store.get");
+      route("/products", "products.get");
+      route("/products/:id", "products.[id].get");
+      route("/categories", "categories.get");
+      route("/brands", "brands.get");
+      route("/cart", "cart.post", "post");
+      route("/cart/:id", "cart.[id].get");
+      route("/cart/:id/items", "cart.[id].items.post", "post");
+      route("/cart/:id/items/:itemId", "cart.[id].items.[itemId].put", "put");
+      route("/cart/:id/items/:itemId", "cart.[id].items.[itemId].delete", "delete");
+      route("/checkout/shipping-methods/:cartId", "checkout.shipping-methods.[cartId].get");
+      route("/checkout/payment-methods/:cartId", "checkout.payment-methods.[cartId].get");
+      route("/checkout/place-order", "checkout.place-order.post", "post");
+      route("/auth/login", "auth.login.post", "post");
+      route("/auth/register", "auth.register.post", "post");
+      route("/auth/logout", "auth.logout.post", "post");
+      route("/auth/forgot-password", "auth.forgot-password.post", "post");
+      route("/auth/reset-password", "auth.reset-password.post", "post");
+      route("/customer", "customer.get");
+      route("/customer/orders", "customer.orders.get");
+      route("/customer/addresses", "customer.addresses.get");
+      route("/customer/addresses", "customer.addresses.post", "post");
+      route("/customer/addresses/:addressId", "customer.addresses.[addressId].put", "put");
+      route("/customer/addresses/:addressId", "customer.addresses.[addressId].delete", "delete");
+      route("/reviews/:productId", "reviews.[productId].get");
+      route("/reviews/:productId/summary", "reviews.[productId].summary.get");
+      route("/reviews", "reviews.post", "post");
+      route("/wishlist", "wishlist.get");
+      route("/wishlist/items", "wishlist.items.post", "post");
+      route("/wishlist/items/:itemId", "wishlist.items.[itemId].delete", "delete");
+      route("/promotions", "promotions.get");
+      route("/promotions/validate", "promotions.validate.post", "post");
+      route("/returns", "returns.get");
+      route("/returns", "returns.post", "post");
+      route("/returns/:returnId", "returns.[returnId].get");
+      route("/returns/:returnId/cancel", "returns.[returnId].cancel.post", "post");
+      route("/countries", "countries.get");
+      route("/locations", "locations.get");
+      logger.info(`Registered ${routeCount} REST API routes under ${apiBase}`);
+    }
+  }
+});
+
+export { commerceModule as default };

package/dist/runtime/composables/index.js

@@ -0,0 +1,15 @@
+export { useAdapter } from "./useAdapter.js";
+export { useProduct } from "./useProduct.js";
+export { useProducts } from "./useProducts.js";
+export { useCategories } from "./useCategories.js";
+export { useCart } from "./useCart.js";
+export { useCustomer } from "./useCustomer.js";
+export { useCheckout } from "./useCheckout.js";
+export { useWishlist } from "./useWishlist.js";
+export { useReviews } from "./useReviews.js";
+export { useStoreInfo } from "./useStoreInfo.js";
+export { usePromotions } from "./usePromotions.js";
+export { useReturns } from "./useReturns.js";
+export { useBrands } from "./useBrands.js";
+export { useCountries } from "./useCountries.js";
+export { useLocations } from "./useLocations.js";

package/dist/runtime/composables/useAdapter.js

@@ -0,0 +1,11 @@
+import { useNuxtApp } from "#imports";
+export function useAdapter() {
+  const nuxtApp = useNuxtApp();
+  const adapter = nuxtApp.$commerce;
+  if (!adapter && import.meta.server) {
+    throw new Error(
+      "[@commercejs/nuxt] No commerce adapter available. Make sure you have installed and configured an adapter package (e.g., @commercejs/adapter-salla, @commercejs/adapter-zid)."
+    );
+  }
+  return adapter || null;
+}

package/dist/runtime/composables/useBrands.js

@@ -0,0 +1,32 @@
+import { useState, readonly } from "#imports";
+import { CommerceError, isCommerceError } from "@commercejs/types";
+import { useAdapter } from "./useAdapter.js";
+export function useBrands() {
+  const adapter = useAdapter();
+  const brands = useState("commerce:brands", () => []);
+  const loading = useState("commerce:brands:loading", () => false);
+  const error = useState("commerce:brands:error", () => null);
+  async function refresh() {
+    loading.value = true;
+    error.value = null;
+    try {
+      brands.value = await adapter.getBrands();
+    } catch (err) {
+      const e = isCommerceError(err) ? err : new CommerceError(
+        err instanceof Error ? err.message : String(err),
+        "UNKNOWN",
+        void 0,
+        err
+      );
+      error.value = e;
+    } finally {
+      loading.value = false;
+    }
+  }
+  return {
+    brands: readonly(brands),
+    loading: readonly(loading),
+    error: readonly(error),
+    refresh
+  };
+}

package/dist/runtime/composables/useCart.js

@@ -0,0 +1,144 @@
+import { useState, useCookie, computed, readonly, useRuntimeConfig } from "#imports";
+import { CommerceError, isCommerceError } from "@commercejs/types";
+import { createEventHook } from "@vueuse/core";
+export function useCart() {
+  const config = useRuntimeConfig();
+  const apiBase = config.public.commerce?.apiBase || "/api/_commerce";
+  const cartId = useCookie("commerce_cart_id", { maxAge: 60 * 60 * 24 * 30 });
+  const cart = useState("commerce_cart", () => null);
+  const loading = useState("commerce_cart_loading", () => false);
+  const error = useState("commerce_cart_error", () => null);
+  const itemAddedHook = createEventHook();
+  const itemUpdatedHook = createEventHook();
+  const itemRemovedHook = createEventHook();
+  const errorHook = createEventHook();
+  function handleError(err) {
+    const e = isCommerceError(err) ? err : new CommerceError(
+      err instanceof Error ? err.message : String(err),
+      "UNKNOWN",
+      void 0,
+      err
+    );
+    error.value = e;
+    errorHook.trigger(e);
+    return e;
+  }
+  async function createCart() {
+    loading.value = true;
+    error.value = null;
+    try {
+      const newCart = await $fetch(`${apiBase}/cart`, { method: "POST" });
+      cart.value = newCart;
+      cartId.value = newCart.id;
+      return newCart;
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function refresh() {
+    if (!cartId.value) return;
+    loading.value = true;
+    error.value = null;
+    try {
+      cart.value = await $fetch(`${apiBase}/cart/${cartId.value}`);
+    } catch (err) {
+      handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function addItem(item) {
+    if (!cartId.value) {
+      throw new Error("[@commercejs/nuxt] No cart ID. Ensure the cart is initialized.");
+    }
+    loading.value = true;
+    error.value = null;
+    try {
+      cart.value = await $fetch(`${apiBase}/cart/${cartId.value}/items`, {
+        method: "POST",
+        body: item
+      });
+      itemAddedHook.trigger(cart.value);
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function updateItem(itemId, quantity) {
+    if (!cartId.value) return;
+    loading.value = true;
+    error.value = null;
+    try {
+      cart.value = await $fetch(`${apiBase}/cart/${cartId.value}/items/${itemId}`, {
+        method: "PUT",
+        body: { quantity }
+      });
+      itemUpdatedHook.trigger(cart.value);
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function removeItem(itemId) {
+    if (!cartId.value) return;
+    loading.value = true;
+    error.value = null;
+    try {
+      cart.value = await $fetch(`${apiBase}/cart/${cartId.value}/items/${itemId}`, {
+        method: "DELETE"
+      });
+      itemRemovedHook.trigger(cart.value);
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function applyCoupon(code) {
+    if (!cartId.value) return;
+    loading.value = true;
+    error.value = null;
+    try {
+      cart.value = await $fetch(`${apiBase}/promotions/validate`, {
+        method: "POST",
+        body: { cartId: cartId.value, code }
+      });
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function removeCoupon() {
+    await refresh();
+  }
+  return {
+    /** Reactive cart state (readonly to enforce mutations through methods) */
+    cart: readonly(cart),
+    /** Cart ID stored in cookie */
+    cartId,
+    /** Whether a cart operation is in progress */
+    loading: readonly(loading),
+    /** Last error from a cart operation */
+    error: readonly(error),
+    /** Number of items in the cart */
+    itemCount: computed(() => cart.value?.itemCount ?? 0),
+    // Event hooks — subscribe: onItemAdded((cart) => { ... })
+    onItemAdded: itemAddedHook.on,
+    onItemUpdated: itemUpdatedHook.on,
+    onItemRemoved: itemRemovedHook.on,
+    onError: errorHook.on,
+    // Methods
+    createCart,
+    refresh,
+    addItem,
+    updateItem,
+    removeItem,
+    applyCoupon,
+    removeCoupon
+  };
+}

package/dist/runtime/composables/useCategories.js

@@ -0,0 +1,9 @@
+import { useFetch, useRuntimeConfig } from "#imports";
+export function useCategories() {
+  const config = useRuntimeConfig();
+  const apiBase = config.public.commerce?.apiBase || "/api/_commerce";
+  return useFetch(
+    `${apiBase}/categories`,
+    { key: "categories" }
+  );
+}

package/dist/runtime/composables/useCheckout.js

@@ -0,0 +1,142 @@
+import { useState, readonly } from "#imports";
+import { CommerceError, isCommerceError } from "@commercejs/types";
+import { createEventHook } from "@vueuse/core";
+import { useAdapter } from "./useAdapter.js";
+import { useCart } from "./useCart.js";
+export function useCheckout() {
+  const adapter = useAdapter();
+  const { cart, cartId } = useCart();
+  const shippingMethods = useState("commerce_shipping_methods", () => []);
+  const paymentMethods = useState("commerce_payment_methods", () => []);
+  const loading = useState("commerce_checkout_loading", () => false);
+  const error = useState("commerce_checkout_error", () => null);
+  const orderPlacedHook = createEventHook();
+  const errorHook = createEventHook();
+  function handleError(err) {
+    const e = isCommerceError(err) ? err : new CommerceError(
+      err instanceof Error ? err.message : String(err),
+      "UNKNOWN",
+      void 0,
+      err
+    );
+    error.value = e;
+    errorHook.trigger(e);
+    return e;
+  }
+  function requireCartId() {
+    if (!cartId.value) {
+      throw new Error("[@commercejs/nuxt] No cart ID found. Add items to cart first.");
+    }
+    return cartId.value;
+  }
+  async function loadShippingMethods() {
+    const id = requireCartId();
+    loading.value = true;
+    error.value = null;
+    try {
+      shippingMethods.value = await adapter.getShippingMethods(id);
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function loadPaymentMethods() {
+    const id = requireCartId();
+    loading.value = true;
+    error.value = null;
+    try {
+      paymentMethods.value = await adapter.getPaymentMethods(id);
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function setShippingAddress(address) {
+    const id = requireCartId();
+    loading.value = true;
+    error.value = null;
+    try {
+      const updatedCart = await adapter.setShippingAddress(id, address);
+      useState("commerce_cart").value = updatedCart;
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function setBillingAddress(address) {
+    const id = requireCartId();
+    loading.value = true;
+    error.value = null;
+    try {
+      const updatedCart = await adapter.setBillingAddress(id, address);
+      useState("commerce_cart").value = updatedCart;
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function setShippingMethod(methodId) {
+    const id = requireCartId();
+    loading.value = true;
+    error.value = null;
+    try {
+      const updatedCart = await adapter.setShippingMethod(id, methodId);
+      useState("commerce_cart").value = updatedCart;
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function setPaymentMethod(methodId) {
+    const id = requireCartId();
+    loading.value = true;
+    error.value = null;
+    try {
+      const updatedCart = await adapter.setPaymentMethod(id, methodId);
+      useState("commerce_cart").value = updatedCart;
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  async function placeOrder() {
+    const id = requireCartId();
+    loading.value = true;
+    error.value = null;
+    try {
+      const order = await adapter.placeOrder(id);
+      useState("commerce_cart").value = null;
+      cartId.value = "";
+      orderPlacedHook.trigger(order);
+      return order;
+    } catch (err) {
+      throw handleError(err);
+    } finally {
+      loading.value = false;
+    }
+  }
+  return {
+    cart,
+    shippingMethods: readonly(shippingMethods),
+    paymentMethods: readonly(paymentMethods),
+    loading: readonly(loading),
+    error: readonly(error),
+    // Event hooks
+    onOrderPlaced: orderPlacedHook.on,
+    onError: errorHook.on,
+    // Methods
+    loadShippingMethods,
+    loadPaymentMethods,
+    setShippingAddress,
+    setBillingAddress,
+    setShippingMethod,
+    setPaymentMethod,
+    placeOrder
+  };
+}

package/dist/runtime/composables/useCountries.js

@@ -0,0 +1,32 @@
+import { useState, readonly } from "#imports";
+import { CommerceError, isCommerceError } from "@commercejs/types";
+import { useAdapter } from "./useAdapter.js";
+export function useCountries() {
+  const adapter = useAdapter();
+  const countries = useState("commerce:countries", () => []);
+  const loading = useState("commerce:countries:loading", () => false);
+  const error = useState("commerce:countries:error", () => null);
+  async function refresh() {
+    loading.value = true;
+    error.value = null;
+    try {
+      countries.value = await adapter.getCountries();
+    } catch (err) {
+      const e = isCommerceError(err) ? err : new CommerceError(
+        err instanceof Error ? err.message : String(err),
+        "UNKNOWN",
+        void 0,
+        err
+      );
+      error.value = e;
+    } finally {
+      loading.value = false;
+    }
+  }
+  return {
+    countries: readonly(countries),
+    loading: readonly(loading),
+    error: readonly(error),
+    refresh
+  };
+}