@zenky/storefront-vue 0.9.47 → 0.10.3

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### Added
+
+- Pull-request CI for formatting, linting, types, coverage, tests, package exports,
+  Node/runtime compatibility, bundle budgets, and secret scanning.
+- Dependabot updates for npm dependencies and GitHub Actions.
+- Public security, contribution, conduct, runtime-port, and release documentation.
+- Coverage ratchet and regression tests for checkout state and credential-safe logging.
+- Cart composables for evaluating product restrictions, confirming blocking
+  restrictions, and reading variants that remain visible after optimistic updates.
+
+### Changed
+
+- GitHub Actions are pinned to immutable commits with minimum workflow permissions.
+- QR-code encoding now uses Web Platform APIs and works without Node `Buffer` or browser
+  globals, improving Node SSR and edge-runtime compatibility.
+- npm package metadata now includes its homepage, issue tracker, and supported engines.
+
+### Fixed
+
+- Empty post-checkout orders no longer trigger a minimum-order-price violation.
+
+### Security
+
+- Cart and checkout errors now pass through recursive redaction before being logged.
+- Direct cart logging no longer emits complete order, credentials, request, or API error
+  objects.
+
+## 0.10.0 - 2026-07-21
+
+### Added
+
+- GitHub release workflow for npm OIDC trusted publishing.
+
+### Changed
+
+- Package renamed to `@zenky/storefront-vue`.
+- Storefront runtime state and cart flows were isolated across Vue applications and SSR
+  requests.

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,222 @@
-# Zenky Storefront Package for Vue 3
+# @zenky/storefront-vue
+
+Headless storefront engine for Zenky — Vue 3 + Pinia, no framework lock-in.
+
+[![CI](https://github.com/zenky/storefront-vue/actions/workflows/ci.yml/badge.svg)](https://github.com/zenky/storefront-vue/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@zenky/storefront-vue.svg)](https://www.npmjs.com/package/@zenky/storefront-vue)
+
+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.68",
+  "@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
 ```
 
-## Usage
+## 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'
+```
+
+The full public contract, adapter examples, SSR lifecycle, and security boundary are in
+[Runtime Ports](docs/ports.md). For a step-by-step consumer integration and upgrade
+checklist, see [Consumer Setup](docs/consumer-setup.md).
+
+## 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`.
+
+## Runtime Compatibility
+
+- ESM-only, targeting ES2022.
+- Vue 3.5+ and Pinia 3.
+- Node.js 20.19+ for SSR and package tooling; Node.js 22 is recommended for production and development.
+- Modern browsers and edge runtimes with standard Web Platform APIs.
+
+CI imports every public entry in Node SSR and scans the emitted ESM for CommonJS, Node
+built-ins, `Buffer`, and `process`. Browser-only behavior is guarded; for example,
+online-payment retry accepts an explicit `currentUrl` when no `window` is available.
+
+For SSR, create a new Vue app, Pinia instance, storefront runtime, and storage adapter per
+request. Never share `createMemoryStorage()` between users.
+
+## Package Size
+
+Every domain has a tree-shakeable subpath. CI measures the transitive gzip graph for the
+root, cart, and utils entries plus all emitted JavaScript. The budgets are regression
+ceilings, not size targets; increasing one requires review and a release-note explanation.
+
+```bash
+npm run build
+npm run check:size
+```
+
+## 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 lint           # Biome lint
+npm run format         # Biome format --write
+npm run typecheck      # tsc --noEmit
+npm test               # vitest
+npm run test:coverage  # vitest + V8 coverage report
+npm run check          # format + lint + types + tests + build + exports
+npm run check:exports  # publint + are-the-types-wrong (esm-only profile)
+npm run check:runtime  # import all entries in SSR + reject Node-only output
+npm run check:size     # enforce gzip bundle budgets
+```
+
+### 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
+```
+
+## Package Scripts
+
+- `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.
+- `check:runtime` — verify Node SSR imports and browser/edge-safe ESM output.
+- `check:size` — enforce root/domain/all-output gzip budgets.
+- `check:ci` — quality gate with the V8 coverage ratchet.
+- `prepublishOnly` — run the release quality gate.
+
+## Contributing and Releases
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. User-visible changes
+belong in [CHANGELOG.md](CHANGELOG.md); maintainer steps are documented in the
+[release process](docs/releasing.md).
 
-Coming soon.
+Security vulnerabilities must be reported privately according to
+[SECURITY.md](SECURITY.md), never through a public issue.
 
 ## License
 
-This project is released under The MIT License (see LICENSE.md).
+MIT