@misiki/nopcommerce-connector

@misiki/nopcommerce-connector

The Official TypeScript API Connector for connecting svelte-commerce to nopCommerce E-Commerce Backend.

@misiki/nopcommerce-connector provides a production-ready, fully-typed API client and integration layer that seamlessly bridges svelte-commerce storefronts with nopCommerce headless e-commerce backends — part of the Litekart connector suite, mirroring the full 43-service surface of @misiki/litekart-connector.

REQUIRED: a paid nopCommerce plugin

nopCommerce core ships no REST API at all. The open-source nopSolutions/nopCommerce project is an ASP.NET Core MVC storefront built on Razor views and antiforgery form posts — there is no /api namespace in it.

This connector talks to /api-frontend, which is the route prefix of the commercial, first-party plugin Nop.Plugin.Misc.WebApi.Frontend ("nopCommerce Web API", Frontend component), sold at https://www.nopcommerce.com/en/web-api. It must be installed alongside its mandatory shared dependency Nop.Plugin.Misc.WebApi.Framework.

Nothing in this package works unless the store owner has purchased and enabled BOTH "Web API Framework" and "Web API Frontend". If the plugin is absent the requests do not 404 into a JSON error — the plugin's base controller is registered with Order = int.MaxValue, so the request falls through to the Razor storefront and returns HTML or a 302. The connector detects that and throws a named PluginNotInstalledError rather than silently returning empty data.

This connector deliberately targets only /api-frontend (storefront, scoped to the JWT's customer). It never uses /api-backend, which requires the administrator-only Access Web API Backend permission and would mean shipping admin credentials inside a storefront client.

Pinned contract: the plugin's controllers are not open source, so every route in this package is pinned to the official OpenAPI 3.0.1 contract nopCommerce publishes on SwaggerHub — nopCommerceAPI/nop-commerce_web_api_frontend v4.50.09 (199 paths, 239 schemas). That is the only published version (2022-08-31), while the plugin's own manifest on the develop branch already reads "Version": "5.00.3", "SupportedVersions": [ "5.00" ] — so the pinned contract is three major lines behind. Treat it as a floor, not a guarantee of parity. Once the plugin is installed, the store serves its own generated contract and Swagger UI at {store location}/api/index.html; for a specific store, that document is the truth.

Known limits of the Frontend API: multi-factor auth cannot be used through it; reCAPTCHA-protected forms (register, contact, password recovery) cannot be satisfied headlessly; there is no DELETE for a cart or wishlist line (use UpdateCart / UpdateWishlist); there is no cart id or cart cookie — the JWT is the session; and detail routes take integer entity ids, so slugs must be resolved via UrlRecord/GetBySlug first.

Setup gotcha: after installing the plugin the store owner must generate a secret key on the plugin's configuration page — that key signs and verifies every JWT. An installed-but-unconfigured plugin fails at Authenticate/GetToken in a way that looks like bad credentials but is not. The same page has a Developer mode switch that disables token verification entirely; if a store reports that the API "works without a token", that is why, and it is wide open.

Coverage: 24 of 43 services are wired to the live nopCommerce API. The remaining 19 have no nopCommerce equivalent and return empty placeholder data. Each placeholder says why in a comment at the top of its service file.

---

Step-by-Step Integration Guide

Follow these steps to connect svelte-commerce with nopcommerce-connector and your nopCommerce backend.

1. Install the Connector

Inside your svelte-commerce project directory, run:

bun i @misiki/nopcommerce-connector

(Or using npm / pnpm / yarn):

npm install @misiki/nopcommerce-connector
# or
pnpm add @misiki/nopcommerce-connector

2. Configure kitcommerce.config.ts

In svelte-commerce, open kitcommerce.config.ts and change the export * line to import from @misiki/nopcommerce-connector:

// kitcommerce.config.ts
export * from '@misiki/nopcommerce-connector';

3. Configure Credentials

Pass apiUrl (your store's root URL — not including /api-frontend, the connector appends that) and optionally accessToken (a JWT from the Web API Frontend plugin).

• API docs: https://docs.nopcommerce.com/en/developer/web-api/index.html (the older /en/developer/api/index.html URL is dead — it returns HTTP 403)
• Route contract: https://app.swaggerhub.com/apis/nopCommerceAPI/nop-commerce_web_api_frontend/v4.50.09
• Swagger UI on your own store, once the plugin is installed: {store location}/api/index.html

Before you can get a token you must generate the secret key on the plugin's configuration page in the admin area — that key signs and verifies every JWT. (The same page has a Developer mode switch that disables token verification entirely; never leave it on in production.)

accessToken is optional. If you omit it the connector bootstraps an anonymous guest session on first use via POST /api-frontend/Authenticate/GetToken with { "is_guest": true } — nopCommerce has no cart cookie, so a guest customer token is what carries an anonymous cart or wishlist. Logging a real customer in replaces that token; an expired customer token is never silently downgraded back to a guest one, so a 401 surfaces as a session error instead of a mysteriously empty order list.

import { NopCommerceConnector } from '@misiki/nopcommerce-connector'

// Credentials are set once, statically — the constructor only takes an optional fetch.
NopCommerceConnector.setCredentials({
  apiUrl: 'https://store.example.com',
  accessToken: 'jwt_token' // optional — omit to run as a guest
})

const client = new NopCommerceConnector()

const products = await client.product.list({ page: 1, sort: '-createdAt' })

4. Build and Run the Project

Run the development server in svelte-commerce:

bun dev

To build and run the production application:

# Build the project
bun run build

# Preview the built application
bun run preview

Service coverage

Service	Status
client.product	live
client.category	live
client.collection	placeholder (no nopCommerce equivalent)
client.order	live
client.coupon	placeholder (no nopCommerce equivalent)
client.address	live
client.review	live
client.cart	live
client.country	live
client.state	live
client.currency	placeholder (no nopCommerce equivalent)
client.region	placeholder (no nopCommerce equivalent)
client.page	live
client.blog	live
client.settings	placeholder (no nopCommerce equivalent)
client.store	placeholder (no nopCommerce equivalent)
client.paymentMethod	live
client.search	live
client.autocomplete	live
client.user	live
client.auth	live
client.profile	live
client.wishlist	live
client.vendor	live
client.checkout	live
client.upload	placeholder (no nopCommerce equivalent)
client.banner	placeholder (no nopCommerce equivalent)
client.chat	placeholder (no nopCommerce equivalent)
client.contact	live
client.deal	placeholder (no nopCommerce equivalent)
client.demoRequest	placeholder (no nopCommerce equivalent)
client.enquiry	placeholder (no nopCommerce equivalent)
client.faq	placeholder (no nopCommerce equivalent)
client.feedback	placeholder (no nopCommerce equivalent)
client.gallery	placeholder (no nopCommerce equivalent)
client.home	live
client.init	live
client.meilisearch	live
client.menu	live
client.plugins	placeholder (no nopCommerce equivalent)
client.popularSearch	placeholder (no nopCommerce equivalent)
client.popularity	placeholder (no nopCommerce equivalent)
client.reels	placeholder (no nopCommerce equivalent)

Development

bun install && bun run typecheck && bun run build

License

MIT misiki-in