@misiki/gocommerce-connector

The Official TypeScript API Connector for connecting svelte-commerce to a GoCommerce backend.

@misiki/gocommerce-connector bridges svelte-commerce storefronts with GoCommerce — "a small, composable commerce engine for Go" — as part of the Litekart connector suite, mirroring the full 43-service surface of @misiki/litekart-connector. It is written against the server's own OpenAPI document (GET /doc on a running store).

Coverage: 10 of 43 services are wired to the live GoCommerce API — catalogue, search, cart, checkout, payment methods and orders. That is the honest ceiling, not a to-do list: GoCommerce is guest-checkout only by design, so there are no accounts, wishlists, reviews, coupons or CMS to wire. Those services answer with empty lists, and their writes throw a named message rather than succeeding silently.

🚀 Step-by-Step Integration Guide

1. Install the Connector

Inside your svelte-commerce project directory, run:

bun i @misiki/gocommerce-connector

(Or using npm / pnpm / yarn):

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

2. Configure kitcommerce.config.ts

In svelte-commerce, open kitcommerce.config.ts and point the services export at the GoCommerce override module:

// kitcommerce.config.ts
export * as services from './src/lib/core/connectors/gocommerce'

export default {
  // store identity overrides — name, logo, favicon, currencyCode, menus, plugins …
}

3. Configure Credentials

The connector needs one thing: the base URL of the GoCommerce server.

PUBLIC_GOCOMMERCE_API_URL='http://127.0.0.1:8080'

svelte-commerce hands that variable to the connector at boot. Outside the storefront, set it directly:

import { BaseService, productService } from '@misiki/gocommerce-connector'

BaseService.setCredentials({ apiUrl: 'http://127.0.0.1:8080' })

const products = await productService.list({ page: 1 })

4. Register store identity

GoCommerce is a commerce engine, not a CMS: it has no record for the store's name, logo, currency, menus, plugin toggles or theme variables. The connector reads them from a provider the storefront registers once at boot:

import { setStaticStore } from '@misiki/gocommerce-connector'

setStaticStore(async () => ({ name: 'My Store', currencyCode: 'USD', /* … */ }))

svelte-commerce does this for you in src/lib/core/connectors/gocommerce.ts, merging default-store.json under the kitcommerce.config.ts default export.

How it works

The browser cannot call GoCommerce directly

GoCommerce sends no Access-Control-Allow-Origin header and answers a preflight with 405. So in the browser every call is sent to API_PROXY_PREFIX (/proxy/gocommerce) on the storefront's own origin, and the storefront forwards it to the API. Server-side calls go straight to PUBLIC_GOCOMMERCE_API_URL. The rule lives in BaseService.apiUrl; media URLs always resolve through the proxy, because a server-rendered <img src> is still fetched by the browser.

svelte-commerce ships that proxy at src/routes/proxy/gocommerce/[...path]/+server.ts. Any other host needs an equivalent route.

Money

GoCommerce sends money as an integer count of the currency's minor unit plus its code ({ amount_minor: 2500, currency: "USD" }). fromMoney converts once, against the currency the amount arrived with, into the plain major-unit number the storefront's components print.

The cart

A cart is an opaque token and possessing it is the whole authorisation. The connector persists it as cart_id. A write that fails is followed by a re-read: if the cart is gone or no longer open, the token is dropped and the item goes into a fresh cart; if the cart is alive, the failure was real and is passed straight through.

The address step, sessions and the address book

GoCommerce has no address on a cart — the delivery address is an argument to POST /api/checkout/{code}. The connector holds the shopper's details in the browser against the cart id (checkout-details) and spends them when the order is placed. Saved addresses are likewise browser-local (address-book); they never leave the device except as part of that call.

Because there are no accounts, a connect.sid / me cookie can only be left over from another backend. hasPhantomSession / clearPhantomSession let the storefront drop them at load.

Checkout, payment and orders

GET /api/checkout lists the installed payment codes; POST /api/checkout/{code} validates the cart, reserves inventory and creates the order in one transaction, with an Idempotency-Key. Gateway fields ride on payment.client_data and are spread onto the return value. Only cod is verified end to end. The order's access_token, returned once, is stored so "my orders" is every order placed from this browser.

Catalogue and search

The shopper-facing catalogue takes q, limit, page and a category or collection slug — no sort, no tag filter, no price range. Sorting and facets are applied in the connector over one window of 200 products, the API's own limit ceiling. Product images are read from both image_url and each variant's image, because the former is missing from the OpenAPI document while the server returns it on every read.

Service behaviour

| Service | Behaviour | | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | ProductService, SearchService | /api/products, /api/products/slug/{slug}, /api/categories/{slug}; sort and facets local | | CategoryService, CollectionService | /api/categories, /api/collections and their slug lookups | | MeilisearchService, AutocompleteService | ?q= on the catalogue — GoCommerce ships no separate search engine | | CartService | /api/carts and its line-items; the address step is held in the browser | | CheckoutService, PaymentMethodService | GET /api/checkout, POST /api/checkout/{code} | | OrderService | /api/orders/{number}?token=…; the confirmation page falls back to the converted cart | | StoreService, MenuService, CurrencyService, PluginService, SettingService, RegionService, … | The registered static store | | AuthService, UserService, ProfileService | No accounts exist — reads answer empty, writes explain why | | AddressService | A browser-local address book | | PageService, BlogService, BannerService, GalleryService, ReelsService | Empty — no CMS | | WishlistService, CouponService, ReviewService, VendorService | Empty lists; writes throw a named message | | ContactService, EnquiryService, UploadService | Throw — there is no inbox behind them |

Development

bun install
bun run typecheck
bun run build      # tsup → dist/ (ESM + CJS + d.ts)
bun p              # build and publish

Source layout (src/services/):

| File | Purpose | | --------------------- | ---------------------------------------------------------- | | base.ts | transport, credentials, the { data, meta } envelope | | types.ts | GoCommerce's wire shapes, from its own OpenAPI document | | money.ts | minor units → the numbers components print | | mappers.ts | GoCommerce → the storefront's (Litekart-shaped) models | | catalog.ts | products, categories, collections, listing search | | cart.ts | the cart token and its lines | | checkout-details.ts | what checkout needs that a GoCommerce cart cannot hold | | address-book.ts | the saved addresses GoCommerce has nowhere to put | | checkout.ts | POST /api/checkout/{code} and the installed payment methods | | orders.ts | guest order lookup by access token | | store.ts | store identity from the registered static config | | static-store.ts | the static store provider and the feature toggles forced off | | unsupported.ts | what GoCommerce deliberately does not have |

License

MIT