@zenky/storefront-vue 0.9.47 → 0.10.3

package/docs/ports.md

@@ -0,0 +1,144 @@
+# Runtime Ports
+
+`@zenky/storefront-vue` follows Ports & Adapters. Domain composables declare the external
+capabilities they need; a storefront supplies concrete adapters once at its composition
+root. This keeps the package portable across Vue SPA, Nuxt SSR, embedded menus, edge
+runtimes, tests, and future storefront templates.
+
+## Dependency direction
+
+```text
+Vue/Nuxt storefront ── creates adapters ──▶ StorefrontRuntime
+                                              │
+UI/components ── call composables ──▶ domain logic ── calls ports ──▶ Zenky SDK/services
+```
+
+The core may know a port interface. It must not know which router, cookie library, toast
+system, WebSocket provider, analytics vendor, or server framework implements that port.
+
+## Runtime contract
+
+Install one runtime per Vue application:
+
+```ts
+import { createStorefront } from '@zenky/storefront-vue'
+import type { StorefrontRuntime } from '@zenky/storefront-vue/ports'
+
+const runtime: StorefrontRuntime = {
+  sdk,
+  config: {
+    baseUrl: 'https://shop.example.com',
+    baseAuthUrl: 'https://auth.example.com',
+    salesChannelId: 'web',
+  },
+  storage,
+  notifier,
+  activity,
+}
+
+app.use(pinia)
+app.use(createStorefront(runtime))
+```
+
+For a locally isolated widget, `provideStorefront(runtime)` can be called inside its setup
+scope instead of installing the plugin globally.
+
+## Required ports
+
+| Port | Contract | Responsibility |
+| --- | --- | --- |
+| `sdk` | `ZenkyStorefront` | Typed access to Zenky Storefront API resources. The consumer owns configuration and request transport. |
+| `config` | `StorefrontConfig` | Public storefront and auth base URLs plus an optional sales channel id. |
+| `storage` | `StorageAdapter` | Synchronous key/value persistence used for order/auth state and lightweight preferences. |
+| `notifier` | `Notifier` | User-facing `error`, `success`, `warning`, and generic message notifications. |
+| `activity` | `ActivityReporter` | Balanced `begin(kind)` / `end(kind)` signals for long-running operations. |
+
+Required ports are intentionally small. If an application has no UI for notifications or
+activity, use `NOOP_NOTIFIER` and `NOOP_ACTIVITY_REPORTER` explicitly.
+
+## Optional ports
+
+| Port | Contract | Behavior when absent |
+| --- | --- | --- |
+| `events` | Lazy `EventsPort.get()` returning `ZenkyIntegrationsSDK` | Integration events are skipped. |
+| `realtime` | Lazy `RealtimePort.get()` returning `RealtimeAdapter` | Realtime order updates are skipped. |
+| `catalogReloader` | `CatalogReloader.reload()` | Stock changes do not trigger an external catalog reload. |
+| `rum` | `RumReporter.mark()` / `measure()` | Performance instrumentation is skipped. |
+| `commerceEvents` | Commerce tracking plus anonymous/session identity | Commerce events and checkout identity enrichment are skipped. |
+
+`events` and `realtime` are providers rather than captured values because integrations can
+be initialized after the storefront runtime. The core resolves them at the moment an event
+is emitted or a subscription is needed.
+
+## Storage adapter
+
+The adapter is synchronous because cart credentials are needed while composables are being
+created. Browser applications can wrap cookies or `localStorage`; SSR applications should
+wrap request/response cookies. `createMemoryStorage()` is intended for tests and isolated,
+request-scoped SSR work only.
+
+```ts
+import type { StorageAdapter } from '@zenky/storefront-vue/ports'
+
+export function createCookieStorage(cookies: CookieStore): StorageAdapter {
+  return {
+    get: (key) => cookies.get(key) ?? null,
+    set: (key, value, options) => {
+      cookies.set(key, value, {
+        path: options?.path ?? '/',
+        maxAge: options?.maxAge,
+        sameSite: options?.sameSite ?? 'lax',
+        secure: options?.secure ?? true,
+      })
+    },
+    remove: (key, options) => cookies.remove(key, { path: options?.path ?? '/' }),
+  }
+}
+```
+
+Do not use one in-memory adapter across users. Do not log storage values. Where the host
+framework permits it, prefer secure, same-site cookies and narrowly scoped paths. Whether a
+cookie can be `httpOnly` depends on where the browser-side SDK needs access to the value.
+
+## SSR and multi-app isolation
+
+For every SSR request, create all three together:
+
+1. a new Pinia instance;
+2. a new `StorefrontRuntime` with request-scoped adapters;
+3. a new Vue application using those instances.
+
+Runtime-owned mutation versions, request deduplication, and related-product state are held
+per runtime. Reusing a runtime or Pinia across requests defeats that isolation and can leak
+state between users.
+
+Public entries are verified by CI through an import in a Node environment without browser
+globals. Built output is also rejected if it contains CommonJS, Node built-in imports,
+`Buffer`, or `process` references. Browser-only actions such as online-payment retry either
+guard `window` access or accept the required URL from the consumer.
+
+## Security boundary
+
+Ports can carry sensitive data even when their types look generic. Adapter implementations
+must not log complete requests, orders, storage records, analytics payloads, or errors from
+unknown SDK transports. The cart/checkout logger redacts common credential shapes as a
+second line of defense, but callers should still pass allow-listed context such as
+`orderId`, operation kind, counts, and booleans.
+
+Never put these values in diagnostic context:
+
+- order or API tokens;
+- `Authorization` and `Cookie` headers;
+- reCAPTCHA payloads and confirmation codes;
+- payment/card token identifiers;
+- customer names, phones, addresses, or free-form order comments.
+
+## Adding or changing a port
+
+Before adding a port, verify that the capability cannot be represented by an existing one.
+Keep the interface vendor-neutral and minimal, document absence/failure behavior, provide a
+no-op implementation when that behavior is meaningful, and add an isolation test.
+
+Adding an optional method is usually backward-compatible. Adding a required port or method,
+changing semantics, or widening when sensitive data is emitted is a breaking change and
+requires a major-version release note.

package/docs/releasing.md

@@ -0,0 +1,46 @@
+# Release Process
+
+Releases are driven by GitHub Releases. Source control keeps
+`"version": "0.0.0-development"`; the publish workflow derives the immutable npm version
+from the release tag.
+
+## Before creating a release
+
+1. Confirm all required CI checks pass on `master`.
+2. Review Dependabot and security alerts.
+3. Move relevant `Unreleased` changelog entries into a new `X.Y.Z - YYYY-MM-DD` section.
+4. Choose the version using Semantic Versioning:
+   - patch for compatible fixes and security hardening;
+   - minor for backward-compatible public features;
+   - major for breaking exports, port contracts, behavior, or support changes.
+5. Verify migrations and compatibility notes are explicit for any consumer-visible change.
+6. Run `npm run check:release` and inspect `npm pack --dry-run` locally.
+
+## Publish
+
+1. Create a GitHub Release for the exact commit to publish.
+2. Tag it `vX.Y.Z`; prereleases may use `vX.Y.Z-beta.N` or `vX.Y.Z-rc.N`.
+3. Generate release notes, then edit them into a consumer-focused summary: outcome first,
+   migrations second, implementation detail last.
+4. Publish the GitHub Release.
+
+The workflow validates the tag, installs with `npm ci`, injects the tag version without
+creating a Git commit, runs the release quality gate, checks package contents, and publishes
+through npm trusted publishing. Stable versions receive the `latest` dist-tag; prereleases
+receive `next`.
+
+The npm package must have a trusted publisher configured for this GitHub repository and the
+`publish-npm.yml` workflow. No long-lived `NPM_TOKEN` should be added.
+
+## Verify
+
+- Confirm the workflow completed and the package has npm provenance.
+- Inspect `npm view @zenky/storefront-vue@X.Y.Z` metadata and dist-tags.
+- Install the exact version into a clean consumer and import both the root and one subpath.
+- Confirm the GitHub release links to the correct tag and changelog section.
+
+## Recovery
+
+Never reuse or move a published version tag. npm versions are immutable. If a release is
+bad, deprecate it with a clear message, fix forward, and publish a new patch or prerelease.
+Reserve unpublishing for exceptional security/legal cases and follow npm policy.

package/package.json

@@ -1,50 +1,146 @@
 {
-  "name": "@zenky/storefront-vue",
-  "version": "0.9.47",
-  "description": "Zenky Storefront library for Vue 3.",
-  "author": "Timur Zurbaev <hello@zurbaev.ru>",
-  "license": "MIT",
-  "exports": {
-    ".": {
-      "require": "./dist/cjs/index.cjs",
-      "import": "./dist/esm/index.mjs"
+    "name": "@zenky/storefront-vue",
+    "version": "0.10.3",
+    "description": "Zenky Storefront SDK for Vue 3.",
+    "keywords": [
+        "zenky",
+        "storefront",
+        "headless",
+        "vue",
+        "pinia",
+        "ecommerce"
+    ],
+    "author": "Zenky",
+    "license": "MIT",
+    "homepage": "https://github.com/zenky/storefront-vue#readme",
+    "bugs": {
+        "url": "https://github.com/zenky/storefront-vue/issues"
+    },
+    "engines": {
+        "node": ">=20.19.0",
+        "npm": ">=10"
+    },
+    "type": "module",
+    "sideEffects": false,
+    "files": [
+        "dist",
+        "docs",
+        "README.md",
+        "CHANGELOG.md",
+        "LICENSE.md"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./ports": {
+            "types": "./dist/ports/index.d.ts",
+            "import": "./dist/ports/index.js"
+        },
+        "./money": {
+            "types": "./dist/money/index.d.ts",
+            "import": "./dist/money/index.js"
+        },
+        "./theme": {
+            "types": "./dist/theme/index.d.ts",
+            "import": "./dist/theme/index.js"
+        },
+        "./utils": {
+            "types": "./dist/utils/index.d.ts",
+            "import": "./dist/utils/index.js"
+        },
+        "./products": {
+            "types": "./dist/products/index.d.ts",
+            "import": "./dist/products/index.js"
+        },
+        "./catalog": {
+            "types": "./dist/catalog/index.d.ts",
+            "import": "./dist/catalog/index.js"
+        },
+        "./cart": {
+            "types": "./dist/cart/index.d.ts",
+            "import": "./dist/cart/index.js"
+        },
+        "./order": {
+            "types": "./dist/order/index.d.ts",
+            "import": "./dist/order/index.js"
+        },
+        "./seo": {
+            "types": "./dist/seo/index.d.ts",
+            "import": "./dist/seo/index.js"
+        },
+        "./layout": {
+            "types": "./dist/layout/index.d.ts",
+            "import": "./dist/layout/index.js"
+        },
+        "./pagination": {
+            "types": "./dist/pagination/index.d.ts",
+            "import": "./dist/pagination/index.js"
+        },
+        "./promotions": {
+            "types": "./dist/promotions/index.d.ts",
+            "import": "./dist/promotions/index.js"
+        },
+        "./snippets": {
+            "types": "./dist/snippets/index.d.ts",
+            "import": "./dist/snippets/index.js"
+        },
+        "./website-settings": {
+            "types": "./dist/website-settings/index.d.ts",
+            "import": "./dist/website-settings/index.js"
+        },
+        "./stores": {
+            "types": "./dist/stores/index.d.ts",
+            "import": "./dist/stores/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "format": "biome format --write .",
+        "format:check": "biome format .",
+        "lint": "biome lint .",
+        "lint:fix": "biome lint --write .",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run",
+        "test:coverage": "vitest run --coverage",
+        "test:watch": "vitest",
+        "check:exports": "publint --strict && attw --pack . --profile esm-only",
+        "check:runtime": "node scripts/check-runtime-compat.mjs",
+        "check:size": "node scripts/check-bundle-size.mjs",
+        "check": "npm run format:check && npm run lint && npm run typecheck && npm run test && npm run build && npm run check:exports && npm run check:runtime && npm run check:size",
+        "check:ci": "npm run format:check && npm run lint && npm run typecheck && npm run test:coverage && npm run build && npm run check:exports && npm run check:runtime && npm run check:size",
+        "check:release": "npm run typecheck && npm run test && npm run build && npm run check:exports && npm run check:runtime && npm run check:size",
+        "prepublishOnly": "npm run check:release"
+    },
+    "peerDependencies": {
+        "@zenky/integrations-sdk": ">=0.1.3",
+        "@zenky/storefront-api": ">=0.0.68",
+        "pinia": "^3.0.0",
+        "vue": "^3.5.0"
+    },
+    "devDependencies": {
+        "@arethetypeswrong/cli": "^0.18.2",
+        "@biomejs/biome": "^2.5.5",
+        "@types/node": "^22.10.0",
+        "@vitest/coverage-v8": "^4.1.10",
+        "@zenky/integrations-sdk": "^0.1.3",
+        "@zenky/storefront-api": "^0.0.68",
+        "pinia": "^3.0.4",
+        "publint": "^0.3.21",
+        "tsup": "^8.3.5",
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.18",
+        "vue": "^3.5.28"
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/zenky/storefront-vue.git"
     }
-  },
-  "main": "./dist/cjs/index.cjs",
-  "module": "./dist/esm/index.mjs",
-  "types": "./dist/zenky.d.ts",
-  "files": [
-    "dist/*"
-  ],
-  "scripts": {
-    "build": "rimraf dist && rimraf build && tsc && rollup -c rollup.config.js",
-    "lint": "eslint \"./src/**/*.ts\"",
-    "fix": "eslint --fix \"./src/**/*.ts\""
-  },
-  "keywords": [
-    "Zenky"
-  ],
-  "peerDependencies": {
-    "@zenky/api": "^0.9.55",
-    "@zenky/events": "^1.0.3",
-    "date-fns": "^2.29.2",
-    "lodash-es": "^4.17.21",
-    "pinia": "^2.0.14",
-    "pusher-js": "^7.1.1-beta",
-    "vue": "^3.2.36"
-  },
-  "devDependencies": {
-    "@types/lodash-es": "^4.17.6",
-    "@typescript-eslint/eslint-plugin": "^5.26.0",
-    "@typescript-eslint/parser": "^5.26.0",
-    "eslint": "^8.16.0",
-    "eslint-config-airbnb": "^19.0.4",
-    "eslint-config-airbnb-base": "^15.0.0",
-    "eslint-config-airbnb-typescript": "^17.0.0",
-    "eslint-plugin-import": "^2.26.0",
-    "rimraf": "^3.0.2",
-    "rollup": "^2.75.0",
-    "rollup-plugin-dts": "^4.2.2",
-    "typescript": "^4.7.2"
-  }
 }