@zenky/storefront-vue 0.9.47 → 0.10.3

package/dist/stores/index.d.ts

@@ -0,0 +1,196 @@
+import * as pinia from 'pinia';
+import * as vue from 'vue';
+import { Ref, ComputedRef } from 'vue';
+import * as _zenky_storefront_api from '@zenky/storefront-api';
+import { CatalogItem, Product, Store, City, Stock, NestedCategory, DeliveryMethod, Order, OrderDeliveryMethod, OrderSettings, OrderCheckoutTotal, PaymentMethod, OrderPaymentTransaction, OrderProductVariant, OrderPaymentMethod } from '@zenky/storefront-api';
+import { Website } from '../website-settings/index.js';
+import '@zenky/integrations-sdk';
+import '../snippets-BC5bkSjm.js';
+
+interface CatalogStore {
+    catalog: Ref<CatalogItem[]>;
+    currentHash: Ref<string | null>;
+    reloading: Ref<boolean>;
+    loadError: Ref<boolean>;
+    initCatalog: (items: CatalogItem[], hash?: string | null) => void;
+    setLoadError: () => void;
+    setReloading: (value: boolean) => void;
+    hasCatalog: ComputedRef<boolean>;
+}
+declare const useCatalogStore: pinia.StoreDefinition<"zenky-catalog", Pick<CatalogStore, "catalog" | "currentHash" | "reloading" | "loadError">, Pick<CatalogStore, "hasCatalog">, Pick<CatalogStore, "initCatalog" | "setLoadError" | "setReloading">>;
+
+interface ProductsStore {
+    products: Ref<Product[]>;
+    setProducts: (list: Product[]) => void;
+    hasProducts: ComputedRef<boolean>;
+}
+declare const useProductsStore: pinia.StoreDefinition<"zenky-products", Pick<ProductsStore, "products">, Pick<ProductsStore, "hasProducts">, Pick<ProductsStore, "setProducts">>;
+
+interface StoreProfileStore {
+    store: Ref<Store | null>;
+    city: Ref<City | null>;
+    stock: Ref<Stock | null>;
+    categories: Ref<NestedCategory[]>;
+    website: Ref<Website | null>;
+    initStore: (store: Store, city: City, stock: Stock | null) => void;
+    setStock: (stock: Stock | null) => void;
+    setCategories: (categories: NestedCategory[]) => void;
+    initWebsite: (website: Website | null) => void;
+    isReady: ComputedRef<boolean>;
+    hasStock: ComputedRef<boolean>;
+    currency: ComputedRef<string>;
+    squareLogoUrl: ComputedRef<string | null>;
+}
+declare const useStoreProfileStore: pinia.StoreDefinition<"zenky-store-profile", Pick<StoreProfileStore, "store" | "city" | "stock" | "categories" | "website">, Pick<StoreProfileStore, "currency" | "isReady" | "hasStock" | "squareLogoUrl">, Pick<StoreProfileStore, "initStore" | "setStock" | "setCategories" | "initWebsite">>;
+
+interface AuthStore {
+    token: Ref<string | null>;
+    phone: Ref<string | null>;
+    countryCode: Ref<string>;
+    isAuthenticated: ComputedRef<boolean>;
+    initials: ComputedRef<string>;
+    setToken: (token: string, phone?: string, countryCode?: string) => void;
+    clearToken: () => void;
+    initFromCookie: () => void;
+}
+declare const useAuthStore: pinia.StoreDefinition<"zenky-auth", Pick<AuthStore, "token" | "phone" | "countryCode">, Pick<AuthStore, "isAuthenticated" | "initials">, Pick<AuthStore, "setToken" | "clearToken" | "initFromCookie">>;
+
+interface OrderSettingsStore {
+    deliveryMethod: Ref<DeliveryMethod>;
+    onPremiseTable: Ref<string | null>;
+    selectedStock: Ref<Stock | null>;
+    selectedAddress: Ref<string | null>;
+    selectedAddressId: Ref<string | null>;
+    selectedAddressName: Ref<string | null>;
+    setDeliveryMethod: (method: DeliveryMethod) => void;
+    setOnPremiseTable: (table: string | null) => void;
+    setSelectedStock: (stock: Stock | null) => void;
+    setSelectedAddress: (address: string | null, addressId?: string | null, addressName?: string | null) => void;
+    validateDeliveryMethod: (availableMethods: DeliveryMethod[]) => void;
+    restoreFromCookies: (city: City) => void;
+    isDelivery: ComputedRef<boolean>;
+    isPickup: ComputedRef<boolean>;
+    isOnPremise: ComputedRef<boolean>;
+    needsAddress: ComputedRef<boolean>;
+    needsStock: ComputedRef<boolean>;
+    needsTable: ComputedRef<boolean>;
+}
+declare const useOrderSettingsStore: pinia.StoreDefinition<"zenky-order-settings", Pick<OrderSettingsStore, "deliveryMethod" | "onPremiseTable" | "selectedStock" | "selectedAddress" | "selectedAddressId" | "selectedAddressName">, Pick<OrderSettingsStore, "isDelivery" | "isPickup" | "isOnPremise" | "needsAddress" | "needsStock" | "needsTable">, Pick<OrderSettingsStore, "setDeliveryMethod" | "setOnPremiseTable" | "setSelectedStock" | "setSelectedAddress" | "validateDeliveryMethod" | "restoreFromCookies">>;
+
+interface CartCredentials {
+    id: string;
+    token: string;
+}
+/** Намерение по бонусам (business-state) — для headless-reconciliation. */
+interface AppliedBonusesIntent {
+    enabled: boolean;
+    /** null = «списать максимум». */
+    desiredAmountMinor: number | null;
+    /** PIN-flow: бонусы сняты, нужно подтвердить заново. */
+    requiresConfirmation: boolean;
+}
+interface MinPriceViolation {
+    remaining: number;
+    progress: number;
+    minPrice: number;
+}
+interface CartStore {
+    order: Ref<Order | null>;
+    credentials: Ref<CartCredentials | null>;
+    loading: Ref<boolean>;
+    initializing: Ref<boolean>;
+    optimisticAdjustments: Ref<Record<string, number>>;
+    lineOptimistic: Ref<Record<string, number>>;
+    deliveryMethods: Ref<OrderDeliveryMethod[]>;
+    orderSettings: Ref<OrderSettings | null>;
+    comment: Ref<string>;
+    personsCount: Ref<number>;
+    checkoutTotal: Ref<OrderCheckoutTotal | null>;
+    selectedPaymentMethod: Ref<PaymentMethod | null>;
+    selectedPaymentBill: Ref<number | null>;
+    selectedCardTokenId: Ref<string | null>;
+    selectedSaveCard: Ref<boolean>;
+    bonusesIntent: Ref<AppliedBonusesIntent>;
+    deliveryTimeIntent: Ref<string | null>;
+    minPriceViolation: Ref<MinPriceViolation | null>;
+    setOrder: (order: Order) => void;
+    patchOrder: (partial: Order) => void;
+    setCredentials: (credentials: CartCredentials) => void;
+    setLoading: (value: boolean) => void;
+    setInitializing: (value: boolean) => void;
+    adjustOptimistic: (productId: string, delta: number) => void;
+    clearOptimistic: (productId: string) => void;
+    adjustLineOptimistic: (lineKey: string, delta: number) => void;
+    setDeliveryMethods: (methods: OrderDeliveryMethod[]) => void;
+    setOrderSettings: (settings: OrderSettings) => void;
+    setComment: (value: string) => void;
+    setPersonsCount: (value: number) => void;
+    setSelectedPaymentMethod: (method: PaymentMethod | null) => void;
+    setSelectedPaymentBill: (bill: number | null) => void;
+    setSelectedCardTokenId: (id: string | null) => void;
+    setSelectedSaveCard: (value: boolean) => void;
+    setBonusesIntentEnabled: (value: boolean) => void;
+    setDesiredBonusesAmount: (value: number | null) => void;
+    setBonusesRequiresConfirmation: (value: boolean) => void;
+    clearBonusesIntent: () => void;
+    setDeliveryTimeIntent: (value: string | null) => void;
+    restorePaymentSelection: (payments: OrderPaymentTransaction[]) => void;
+    validatePaymentSelection: () => void;
+    setOrderPaymentsState: (payments: OrderPaymentTransaction[]) => void;
+    setCheckoutTotal: (value: OrderCheckoutTotal) => void;
+    clearCart: () => void;
+    hasOrder: ComputedRef<boolean>;
+    hasCredentials: ComputedRef<boolean>;
+    variants: ComputedRef<OrderProductVariant[]>;
+    totalPrice: ComputedRef<number>;
+    itemCount: ComputedRef<number>;
+    availableDeliveryMethodIds: ComputedRef<DeliveryMethod[]>;
+    paymentMethods: ComputedRef<OrderPaymentMethod[]>;
+    hasBonusesApplied: ComputedRef<boolean>;
+    productQuantities: ComputedRef<Record<string, number>>;
+}
+declare const useCartStore: pinia.StoreDefinition<"zenky-cart", Pick<CartStore, "order" | "credentials" | "loading" | "initializing" | "optimisticAdjustments" | "lineOptimistic" | "deliveryMethods" | "orderSettings" | "comment" | "personsCount" | "checkoutTotal" | "selectedPaymentMethod" | "selectedPaymentBill" | "selectedCardTokenId" | "selectedSaveCard" | "bonusesIntent" | "deliveryTimeIntent" | "minPriceViolation">, Pick<CartStore, "hasOrder" | "hasCredentials" | "variants" | "totalPrice" | "itemCount" | "availableDeliveryMethodIds" | "paymentMethods" | "hasBonusesApplied" | "productQuantities">, Pick<CartStore, "setOrder" | "patchOrder" | "setCredentials" | "setLoading" | "setInitializing" | "adjustOptimistic" | "clearOptimistic" | "adjustLineOptimistic" | "setDeliveryMethods" | "setOrderSettings" | "setComment" | "setPersonsCount" | "setSelectedPaymentMethod" | "setSelectedPaymentBill" | "setSelectedCardTokenId" | "setSelectedSaveCard" | "setBonusesIntentEnabled" | "setDesiredBonusesAmount" | "setBonusesRequiresConfirmation" | "clearBonusesIntent" | "setDeliveryTimeIntent" | "restorePaymentSelection" | "validatePaymentSelection" | "setOrderPaymentsState" | "setCheckoutTotal" | "clearCart">>;
+
+interface RewardSelectionContext {
+    type: string;
+    id: string;
+}
+interface RewardSelection {
+    offerId: string;
+    promotionId: string;
+    rewardId: string;
+    context: RewardSelectionContext | null;
+    limit: number;
+}
+interface PromotionsStore {
+    rewards: Ref<RewardSelection[]>;
+    checking: Ref<boolean>;
+    addOrUpdateReward: (selection: RewardSelection) => void;
+    removeRewardByPromotion: (promotionId: string) => void;
+    clearRewards: () => void;
+    setChecking: (value: boolean) => void;
+    hasRewards: ComputedRef<boolean>;
+    totalEmptySlots: ComputedRef<number>;
+    rewardSelection: ComputedRef<RewardSelection | null>;
+    needsSelection: ComputedRef<boolean>;
+}
+declare const usePromotionsStore: pinia.StoreDefinition<"zenky-promotions", Pick<PromotionsStore, "rewards" | "checking">, Pick<PromotionsStore, "hasRewards" | "totalEmptySlots" | "rewardSelection" | "needsSelection">, Pick<PromotionsStore, "addOrUpdateReward" | "removeRewardByPromotion" | "clearRewards" | "setChecking">>;
+
+/** Аксессор загруженного стора/города/склада (store/city — гарантированно загружены). */
+declare function useStore(): {
+    store: ComputedRef<Store>;
+    city: ComputedRef<City>;
+    stock: ComputedRef<Stock | null>;
+};
+
+/** Реактивный доступ к профилю (store/city/stock/categories + флаги готовности). */
+declare function useStorefrontProfile(): {
+    store: vue.Ref<_zenky_storefront_api.Store | null, _zenky_storefront_api.Store | null>;
+    city: vue.Ref<_zenky_storefront_api.City | null, _zenky_storefront_api.City | null>;
+    stock: vue.Ref<_zenky_storefront_api.Stock | null, _zenky_storefront_api.Stock | null>;
+    categories: vue.Ref<_zenky_storefront_api.NestedCategory[], _zenky_storefront_api.NestedCategory[]>;
+    isReady: vue.ComputedRef<boolean>;
+    hasStock: vue.ComputedRef<boolean>;
+};
+
+export { type AppliedBonusesIntent, type AuthStore, type CartStore, type MinPriceViolation, type OrderSettingsStore, type PromotionsStore, type RewardSelection, type RewardSelectionContext, type StoreProfileStore, useAuthStore, useCartStore, useCatalogStore, useOrderSettingsStore, useProductsStore, usePromotionsStore, useStore, useStoreProfileStore, useStorefrontProfile };

package/dist/stores/index.js

@@ -0,0 +1,8 @@
+export { useProductsStore, useStore, useStorefrontProfile } from '../chunk-57IOMDAM.js';
+export { useCatalogStore } from '../chunk-Z3IW4ODZ.js';
+export { usePromotionsStore } from '../chunk-BWUKMWHL.js';
+export { useAuthStore, useStoreProfileStore } from '../chunk-TEG7EL4N.js';
+export { useCartStore, useOrderSettingsStore } from '../chunk-FFBZKQRV.js';
+import '../chunk-V3VVDQIR.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/stores/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/theme/index.d.ts

@@ -0,0 +1,60 @@
+import { ComputedRef } from 'vue';
+
+interface ThemeColorConfig {
+    primary: string;
+    secondary: string;
+    accent: string;
+    background: string;
+    text: string;
+    success?: string;
+    danger?: string;
+    warning?: string;
+    info?: string;
+    /** Цвет текста поверх primary-фона. Если не задан — рассчитывается автоматически. */
+    onPrimary?: string;
+    headerBg?: string;
+    footerBg?: string;
+    footerText?: string;
+    footerTextMuted?: string;
+}
+interface PrimaryShades {
+    lightest: string;
+    lighter: string;
+    light: string;
+    base: string;
+    dark: string;
+    darker: string;
+    darkest: string;
+    tint: string;
+    tintHover: string;
+    tintPressed: string;
+    ink: string;
+}
+/** Универсальный генератор 11-ступенчатой шкалы от одного hex. */
+declare function generateShades(hex: string, bg?: string, text?: string): PrimaryShades;
+declare function generatePrimaryShades(hex: string, bg?: string, text?: string): PrimaryShades;
+declare function buildCssVariableMap(config: ThemeColorConfig): Record<string, string>;
+
+interface FontConfig {
+    family: string;
+    url: string;
+}
+interface ThemeData {
+    cssVariables: ComputedRef<Record<string, string>>;
+    fontFamily: ComputedRef<string | null>;
+    fontUrl: ComputedRef<string | null>;
+}
+/** CSS-переменные темы + шрифт из цвето-/шрифто-конфига (инъекция в head — на стороне app). */
+declare function useTheme(colorConfig: ThemeColorConfig, fontConfig: FontConfig): ThemeData;
+
+interface ThemePreset {
+    id: string;
+    label: string;
+    description: string;
+    colors: ThemeColorConfig;
+}
+declare const THEME_PRESETS: ThemePreset[];
+/** Тёмные версии пресетов — инвертированные background/text */
+declare const DARK_THEME_PRESETS: ThemePreset[];
+
+export { DARK_THEME_PRESETS, type FontConfig, type PrimaryShades, THEME_PRESETS, type ThemeColorConfig, type ThemeData, type ThemePreset, buildCssVariableMap, generatePrimaryShades, generateShades, useTheme };

package/dist/theme/index.js

@@ -0,0 +1,3 @@
+export { DARK_THEME_PRESETS, THEME_PRESETS, buildCssVariableMap, generatePrimaryShades, generateShades, useTheme } from '../chunk-GW2QNTAD.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/theme/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/utils/index.d.ts

@@ -0,0 +1,66 @@
+import { Phone } from '@zenky/storefront-api';
+export { D as DayScheduleInfo, S as SocialLink, T as TodayScheduleInfo, f as formatScheduleStatus, g as getEmailLink, a as getSocialLinks, b as getTodayInfo, c as getWebsiteLink, d as getWeeklySchedule } from '../schedule-Dd3zwHEb.js';
+
+declare function createDebounce(fn: () => void, delay: number): () => void;
+
+interface OperationChain {
+    execute: (key: string, fn: () => Promise<void>) => Promise<void>;
+    readonly size: number;
+}
+declare function createOperationChain(): OperationChain;
+
+declare function formatPhoneNational(phone: Phone | null | undefined): string | null;
+declare function getPhoneTelLink(phone: Phone | null | undefined): string | null;
+/**
+ * «Воздушный» формат номера: `+7 (999) 999-99-99` → `+7 999 999 99 99`.
+ * Скобки и дефисы заменяются на пробелы, лишние пробелы схлопываются.
+ */
+declare function formatPhoneSpaced(formatted: string | null | undefined): string;
+
+/**
+ * Генерирует URL картинки QR-кода через Zenky media API.
+ *
+ * Контент кодируется в base64 и передаётся в query `content`.
+ * Реализация не зависит от `window`, `btoa` или Node.js `Buffer`, поэтому один
+ * и тот же код работает в браузере, Node SSR и edge runtimes.
+ */
+declare function buildQrCodeUrl(target: string, apiBaseUrl: string, size?: number): string;
+
+declare function formatDate(date: string): string;
+declare function formatDateTime(date: string): string;
+/**
+ * Извлекает YYYY-MM-DD из ISO-строки (например "1998-06-02T03:00:00+03:00" → "1998-06-02").
+ * Для использования в <input type="date">.
+ */
+declare function toDateInputValue(value: string | null): string;
+/**
+ * Сегодняшняя дата в указанном часовом поясе в формате YYYY-MM-DD.
+ * Если TZ невалидный или не передан — возвращает дату в локальном TZ браузера.
+ *
+ * Используется, когда нужно сопоставить «сегодня» с датой из бэка, которая
+ * приходит относительно TZ магазина (а не TZ пользователя).
+ */
+declare function todayInTimezone(timezone?: string | null): string;
+
+/**
+ * Склонение существительных по числу (русский язык).
+ *
+ * @example
+ * pluralize(1, 'позиция', 'позиции', 'позиций') // 'позиция'
+ * pluralize(3, 'позиция', 'позиции', 'позиций') // 'позиции'
+ * pluralize(5, 'позиция', 'позиции', 'позиций') // 'позиций'
+ */
+declare function pluralize(count: number, one: string, few: string, many: string): string;
+
+/** Сообщение из ZenkyError (или fallback). */
+declare function getApiErrorMessage(e: unknown, fallback: string): string;
+/** Field-level ошибки из `meta.errors` ответа API (422 validation). */
+declare function getApiFieldErrors(e: unknown): Record<string, string[]> | null;
+
+/**
+ * Переносит город в конец строки адреса.
+ * "г Улан-Удэ, ул Ленина, д 29" → "ул Ленина, д 29, г Улан-Удэ"
+ */
+declare function formatAddressCityLast(raw: string): string;
+
+export { type OperationChain, buildQrCodeUrl, createDebounce, createOperationChain, formatAddressCityLast, formatDate, formatDateTime, formatPhoneNational, formatPhoneSpaced, getApiErrorMessage, getApiFieldErrors, getPhoneTelLink, pluralize, toDateInputValue, todayInTimezone };

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+export { buildQrCodeUrl, createOperationChain, formatAddressCityLast, formatDate, formatDateTime, formatPhoneNational, formatPhoneSpaced, formatScheduleStatus, getApiErrorMessage, getApiFieldErrors, getEmailLink, getPhoneTelLink, getSocialLinks, getTodayInfo, getWebsiteLink, getWeeklySchedule, pluralize, toDateInputValue, todayInTimezone } from '../chunk-MZ66ARDL.js';
+export { createDebounce } from '../chunk-XUGXLJZB.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/website-settings/index.d.ts

@@ -0,0 +1,38 @@
+import { Media } from '@zenky/storefront-api';
+import { ZenkyIntegration } from '@zenky/integrations-sdk';
+import { a as SnippetGroup } from '../snippets-BC5bkSjm.js';
+
+type SettingValue = string | number | boolean | null;
+interface WebsiteSettingsValues {
+    [key: string]: SettingValue | {
+        [key: string]: SettingValue | {
+            [key: string]: SettingValue;
+        };
+    };
+}
+type WebsitePageType = 'about_us' | 'delivery_and_payments' | 'contacts' | 'custom';
+interface WebsitePageSeo {
+    title?: string | null;
+    description?: string | null;
+    og_image?: string | null;
+}
+interface WebsitePageListItem {
+    id: string;
+    type: WebsitePageType;
+    path: string | null;
+    title?: string;
+}
+interface WebsitePage extends WebsitePageListItem {
+    content: string | null;
+    cover: Media | null;
+    seo: WebsitePageSeo | null;
+}
+interface Website {
+    id: string;
+    settings: WebsiteSettingsValues;
+    pages?: WebsitePageListItem[];
+    snippets?: SnippetGroup[];
+    integrations?: ZenkyIntegration[];
+}
+
+export type { SettingValue, Website, WebsitePage, WebsitePageListItem, WebsitePageSeo, WebsitePageType, WebsiteSettingsValues };

package/dist/website-settings/index.js

@@ -0,0 +1,3 @@
+import '../chunk-EMGQXBU3.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/website-settings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/docs/consumer-setup.md

@@ -0,0 +1,275 @@
+# Consumer Setup
+
+This guide is for teams integrating `@zenky/storefront-vue` into a Vue or Nuxt
+storefront. The package owns reusable storefront state and business flows. The consumer
+owns framework glue, visual components, routing, server endpoints, and environment
+configuration.
+
+## 1. Install an exact version
+
+Use an exact version while integrating or testing a prerelease. Upgrade deliberately
+after the consumer quality gate is green.
+
+```bash
+npm install --save-exact @zenky/storefront-vue@0.10.0
+```
+
+The consumer must also provide compatible peer dependencies:
+
+```bash
+npm install vue@^3.5 pinia@^3 @zenky/storefront-api@^1
+```
+
+Install `@zenky/integrations-sdk` when the consumer sends Zenky integration events.
+
+Do not commit a `file:.yalc/...` dependency. `yalc` is only for local development; CI
+and deployed environments must install a published package version.
+
+## 2. Decide which domains the consumer needs
+
+Import public subpaths instead of application source files:
+
+```ts
+import { createStorefront } from '@zenky/storefront-vue'
+import { getRemoteCatalog } from '@zenky/storefront-vue/catalog'
+import { useProductPricing } from '@zenky/storefront-vue/products'
+import { useCartStore } from '@zenky/storefront-vue/stores'
+```
+
+A read-only menu normally needs `catalog`, `products`, `theme`, `utils`, and selected
+stores. It does not need cart, checkout, auth, delivery, or payment modules.
+
+A full storefront can additionally use `cart`, `order`, `promotions`, `seo`, `layout`,
+`pagination`, `snippets`, and `website-settings`.
+
+Never import from `@zenky/storefront-vue/dist/*` or from this repository's `src/*`.
+Only documented package exports are public API.
+
+## 3. Create one composition root
+
+The consumer creates external adapters once and installs the storefront plugin after
+Pinia.
+
+```ts
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import { createStorefront } from '@zenky/storefront-vue'
+import type { StorefrontRuntime } from '@zenky/storefront-vue/ports'
+
+import App from './App.vue'
+import { sdk } from './services/zenky'
+
+const app = createApp(App)
+const pinia = createPinia()
+
+const runtime: StorefrontRuntime = {
+  sdk,
+  config: {
+    baseUrl: import.meta.env.VITE_STOREFRONT_URL,
+    baseAuthUrl: import.meta.env.VITE_AUTH_URL,
+    salesChannelId: import.meta.env.VITE_SALES_CHANNEL_ID || undefined,
+  },
+  storage: {
+    get: (key) => localStorage.getItem(key),
+    set: (key, value) => localStorage.setItem(key, value),
+    remove: (key) => localStorage.removeItem(key),
+  },
+  notifier: {
+    error: (message) => notifications.error(message),
+    success: (message) => notifications.success(message),
+    warning: (message) => notifications.warning(message),
+    message: (title, options) => notifications.message(title, options),
+  },
+  activity: {
+    begin: (kind) => busy.begin(kind),
+    end: (kind) => busy.end(kind),
+  },
+}
+
+app.use(pinia)
+app.use(createStorefront(runtime))
+app.mount('#app')
+```
+
+Use `NOOP_NOTIFIER` and `NOOP_ACTIVITY_REPORTER` from the `ports` subpath when a
+read-only consumer intentionally has no notifications or busy UI. Keep that decision
+explicit.
+
+## 4. Nuxt adapter
+
+Nuxt consumers should install the runtime in one plugin and keep Nuxt APIs in that
+plugin, not in the package.
+
+```ts
+import { createStorefront } from '@zenky/storefront-vue'
+import type { StorefrontRuntime } from '@zenky/storefront-vue/ports'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig()
+
+  const runtime: StorefrontRuntime = {
+    sdk: useStorefrontApi(),
+    config: {
+      baseUrl: config.public.storefrontBaseUrl,
+      baseAuthUrl: config.public.storefrontAuthUrl,
+    },
+    storage: {
+      get: (key) => useCookie<string | null>(key).value ?? null,
+      set: (key, value, options) => {
+        useCookie<string>(key, options).value = value
+      },
+      remove: (key, options) => {
+        useCookie(key, options).value = null
+      },
+    },
+    notifier: createNotifierAdapter(),
+    activity: createActivityAdapter(),
+  }
+
+  nuxtApp.vueApp.use(createStorefront(runtime))
+})
+```
+
+Resolve optional integrations lazily when their initialization order is later than the
+storefront plugin:
+
+```ts
+runtime.events = {
+  get: () => useZenkyIntegrations(),
+}
+
+runtime.realtime = {
+  get: () => useRealtimeAdapter(),
+}
+```
+
+Do not capture an initial `null` integration instance during plugin setup.
+
+## 5. Storage and sensitive data
+
+The storage adapter is synchronous because order and auth credentials are read while
+composables are created.
+
+For browser-only applications, `localStorage` or cookies are acceptable according to
+the consumer's security model. For SSR, use request-scoped cookies.
+
+Never:
+
+- share in-memory storage between users;
+- log storage values, order tokens, API tokens, cookies, confirmation codes, payment
+  tokens, phone numbers, addresses, or order comments;
+- expose secret server configuration through public runtime config;
+- persist real credentials in test fixtures.
+
+See [Runtime Ports](ports.md) for the complete security boundary.
+
+## 6. SSR isolation
+
+For every server request, create a new:
+
+1. Vue application;
+2. Pinia instance;
+3. `StorefrontRuntime`;
+4. storage adapter.
+
+Do not keep runtime or Pinia instances in module-global server state. Runtime-owned
+mutation versions, request deduplication, restriction gates, and related-product state
+must not cross request or application boundaries.
+
+## 7. Local package development with yalc
+
+Use `yalc` only when changing the package and consumer together.
+
+In this repository:
+
+```bash
+npm run build
+npx yalc publish
+```
+
+In the consumer:
+
+```bash
+npx yalc add @zenky/storefront-vue
+```
+
+After another package change:
+
+```bash
+npm run build
+npx yalc push
+```
+
+Before committing the consumer:
+
+```bash
+npx yalc remove @zenky/storefront-vue
+npm install --save-exact @zenky/storefront-vue@<published-version>
+```
+
+Verify that `package.json` and `package-lock.json` no longer reference `.yalc`.
+
+## 8. Consumer quality gate
+
+Before requesting review:
+
+```bash
+npm ci
+npm run lint
+npm run test
+npm run build
+```
+
+For Nuxt consumers, also verify:
+
+- the first SSR request returns HTML without a storefront-runtime or Pinia error;
+- hydration completes without mismatch warnings;
+- a new browser session creates or restores the expected order;
+- a second app or SSR request does not see the first user's state;
+- optional integrations initialized after the runtime still receive events.
+
+For cart or checkout changes, cover:
+
+- add, increment, decrement, and clear;
+- API failures and stale responses;
+- delivery and payment selection;
+- minimum-order behavior;
+- product restrictions;
+- cleanup of busy state.
+
+## 9. Upgrade checklist
+
+1. Read the package changelog and migration notes.
+2. Install the exact target version.
+3. Review changed ports and exported types.
+4. Run the package consumer's unit tests and production build.
+5. Run smoke tests against a dedicated development store.
+6. Deploy to development.
+7. Run the same smoke suite against the deployed URL.
+8. Only then widen the version range or promote a prerelease.
+
+## 10. Common failures
+
+### `createStorefront() is not installed`
+
+The runtime plugin was not installed, was installed after a component used the package,
+or a second Vue application did not receive its own runtime.
+
+### `getActivePinia()` or `No active Pinia`
+
+Install Pinia before `createStorefront(runtime)` and before calling package stores.
+
+### The app builds locally but CI cannot install the package
+
+Check `package.json` and the lockfile for `file:.yalc`, local paths, or an unpublished
+version.
+
+### SSR users share cart or restriction state
+
+A runtime, Pinia instance, or storage adapter is being reused between requests. Make all
+three request-scoped.
+
+### An optional integration never receives events
+
+Provide a lazy `{ get() }` adapter instead of capturing the integration instance before
+it is initialized.