@misiki/gocommerce-connector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 misiki-in
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# @misiki/gocommerce-connector
+
+[![NPM Version](https://img.shields.io/npm/v/@misiki/gocommerce-connector.svg)](https://www.npmjs.com/package/@misiki/gocommerce-connector)
+[![License](https://img.shields.io/npm/l/@misiki/gocommerce-connector.svg)](https://github.com/misiki-in/gocommerce-connector/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+**The Official TypeScript API Connector for connecting `svelte-commerce` to a GoCommerce backend.**
+
+`@misiki/gocommerce-connector` bridges [svelte-commerce](https://github.com/misiki-in/svelte-commerce) storefronts with [GoCommerce](https://github.com/itswadesh/gocommerce) — "a small, composable commerce engine for Go" — as part of the [Litekart](https://litekart.in) connector suite, mirroring the full 43-service surface of [`@misiki/litekart-connector`](https://github.com/misiki-in/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:
+
+```bash
+bun i @misiki/gocommerce-connector
+```
+
+*(Or using npm / pnpm / yarn):*
+```bash
+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:
+
+```typescript
+// 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.
+
+```env
+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:
+
+```ts
+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:
+
+```ts
+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
+
+```bash
+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