@zenky/storefront-vue 0.9.47 → 0.10.0

package/LICENSE.md

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2022 Zenky
+Copyright (c) 2026 Zenky
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,15 +1,172 @@
-# Zenky Storefront Package for Vue 3
+# @zenky/storefront-vue
+
+Headless storefront engine for Zenky — Vue 3 + Pinia, no framework lock-in.
+
+One engine behind many storefronts. The cart, order building, checkout, catalog resolution, delivery slots, SEO/JSON-LD, theme, and store/profile state all live here as framework-agnostic composables and Pinia stores. The consumer — a Nuxt site, a QR-code menu, a new template — brings the framework glue (cookies, config, toasts, HTTP transport, `useHead`) and draws its own UI on top.
+
+The design is Ports & Adapters: the core declares small ports for everything it needs from the outside world, the consumer provides adapters once, and every composable reads them through `useRuntime()`. The core never imports `useCookie`, `useRoute`, `useHead`, `$fetch`, or anything Nuxt-specific.
 
 ## Installation
 
-```shell
-npm i --save @zenky/storefront-vue
+```bash
+npm install @zenky/storefront-vue
+```
+
+Peer dependencies (the consumer already has these):
+
+```jsonc
+{
+  "vue": "^3.5.0",
+  "pinia": "^3.0.0",
+  "@zenky/storefront-api": ">=0.0.64",
+  "@zenky/integrations-sdk": ">=0.1.3"
+}
+```
+
+## Quick Start
+
+Assemble the runtime once at your composition root and install it as a Vue plugin. After that, core composables just work.
+
+```ts
+import { createStorefront } from '@zenky/storefront-vue'
+
+app.use(
+  createStorefront({
+    sdk,                                    // ZenkyStorefront instance (one per app)
+    config: { baseUrl, baseAuthUrl },
+    storage: {                              // where order id/token, settings, etc. persist
+      get: (key) => readCookie(key),
+      set: (key, value, opts) => writeCookie(key, value, opts),
+      remove: (key, opts) => deleteCookie(key, opts),
+    },
+    notifier: {                             // user-facing messages
+      error: (m) => toast.error(m),
+      success: (m) => toast.success(m),
+      warning: (m) => toast.warning(m),
+      message: (title, opts) => toast(title, opts),
+    },
+    activity: {                             // busy indicators for long operations
+      begin: (kind) => busy.begin(kind),
+      end: (kind) => busy.end(kind),
+    },
+  }),
+)
+```
+
+Then, anywhere in a component or composable:
+
+```ts
+import { useStorefrontCart } from '@zenky/storefront-vue/cart'
+
+const cart = useStorefrontCart()
+
+await cart.initializeOrder()
+await cart.addToCart({ productId, productVariantId, quantity: 1 })
+
+cart.itemCount.value // reactive
+cart.totalPrice.value
+```
+
+## Runtime Ports
+
+`createStorefront(runtime)` takes one object. Five ports are required; the rest are optional — omit an optional port and the feature that needs it is simply skipped.
+
+| Port | Required | What the consumer provides |
+| --- | --- | --- |
+| `sdk` | yes | A `ZenkyStorefront` instance (`@zenky/storefront-api`). |
+| `config` | yes | `{ baseUrl, baseAuthUrl, salesChannelId? }`. |
+| `storage` | yes | Key/value persistence — cookies, `localStorage`, memory. |
+| `notifier` | yes | Toasts: `error` / `success` / `warning` / `message`. |
+| `activity` | yes | `begin(kind)` / `end(kind)` for busy state. |
+| `events` | no | Lazy `{ get() }` provider for `ZenkyIntegrationsSDK`; resolve on every event. |
+| `realtime` | no | Lazy `{ get() }` provider for the WebSocket adapter (`subscribe` / `unsubscribe` / `isReady`). |
+| `catalogReloader` | no | Reloads the catalog when the stock changes. |
+| `rum` | no | Performance marks (`mark` / `measure`). |
+| `commerceEvents` | no | Commerce-event tracking (`trackAddedToCart`, `getIdentity`, …). |
+
+Types for every port live in the `ports` subpath, alongside no-op defaults and an in-memory storage helper for SSR/tests:
+
+```ts
+import {
+  type StorefrontRuntime,
+  type StorageAdapter,
+  NOOP_NOTIFIER,
+  NOOP_ACTIVITY_REPORTER,
+  createMemoryStorage,
+} from '@zenky/storefront-vue/ports'
+```
+
+## Subpath Imports
+
+Each public domain is its own entry point, so bundlers only pull in what you import.
+
+```ts
+import { minorToMajor } from '@zenky/storefront-vue/money'
+import { buildCssVariableMap, THEME_PRESETS } from '@zenky/storefront-vue/theme'
+import { getRemoteCatalog, findCategoryByShortId } from '@zenky/storefront-vue/catalog'
+import { useStorefrontCart, useCheckoutSubmit } from '@zenky/storefront-vue/cart'
+import { generateFreeTimeGroups } from '@zenky/storefront-vue/order'
+import { buildProductSchema, buildOgTags } from '@zenky/storefront-vue/seo'
+import { useHeaderData, useFooterData } from '@zenky/storefront-vue/layout'
+import { usePaginatedList } from '@zenky/storefront-vue/pagination'
+```
+
+Available subpaths: `ports`, `money`, `utils`, `theme`, `stores`, `products`, `catalog`, `cart`, `order`, `promotions`, `seo`, `layout`, `pagination`, `snippets`, `website-settings`.
+
+## Pinia Stores
+
+The `stores` subpath exposes setup-style Pinia stores (ids namespaced `zenky-*`): cart, order settings, store profile, catalog, products, auth, promotions. They are plain state containers — no API calls, no UI logic — and they are the reactive backbone the composables read from. Install Pinia before mounting the storefront plugin.
+
+```ts
+import { useCartStore, useStoreProfileStore } from '@zenky/storefront-vue/stores'
+```
+
+## Money
+
+Prices are stored and computed in minor units (kopecks) everywhere. Convert only at the API boundary.
+
+```ts
+import { minorToMajor, minorToMajorString, majorToMinor } from '@zenky/storefront-vue/money'
+
+minorToMajor(65000, 'RUB')       // 650    — numbers for bill/amount fields
+minorToMajorString(65000, 'RUB') // "650.00" — strings where the API expects them
+majorToMinor(650, 'RUB')         // 65000  — user input back into the store
+```
+
+## Development
+
+```bash
+npm run dev            # tsup --watch
+npm run build          # ESM + .d.ts to dist/
+npm run typecheck      # tsc --noEmit
+npm test               # vitest
+npm run check:exports  # publint + are-the-types-wrong (esm-only profile)
+```
+
+### Local linking with yalc
+
+Until the package is published, link it into a consumer app with [yalc](https://github.com/wclr/yalc):
+
+```bash
+# in this package, after a build:
+npx yalc publish
+
+# in the consumer app:
+npx yalc add @zenky/storefront-vue
+
+# after each change here:
+npm run build && npx yalc push
 ```
 
-## Usage
+## Package Scripts
 
-Coming soon.
+- `build` — bundle the multi-entry ESM package with tsup.
+- `dev` — rebuild on change.
+- `test` / `test:watch` — run the Vitest suite.
+- `typecheck` — type-only compile.
+- `check:exports` — validate the exports map and published types.
+- `prepublishOnly` — typecheck → test → build → check:exports.
 
 ## License
 
-This project is released under The MIT License (see LICENSE.md).
+MIT