@teamnovu/kit-shopware-composables 0.0.3 → 0.0.4

package/docs/index.md

@@ -0,0 +1,457 @@
+# Shopware Composables
+
+A comprehensive collection of Vue 3 composables for Shopware Store API integration with TanStack Query for state management and caching.
+
+Install with `npm i @teamnovu/kit-shopware-composables`
+
+## Features
+
+- ✅ **Vue 3 Composition API** - Built for Vue 3 with full TypeScript support
+- ✅ **TanStack Query Integration** - Powerful caching, background updates, and query management
+- ✅ **Type-safe Operations** - Generated types from Shopware API schema
+- ✅ **Modular Architecture** - Import only what you need
+- ✅ **Optimistic Updates** - Smooth UX with optimistic mutation handling
+- ✅ **Docker Development** - Ready-to-use Shopware development environment
+
+## Quick Start
+
+```typescript
+import { 
+  useReadProductListingQuery,
+  useReadCartQuery,
+  useAddLineItemMutation,
+  usePaymentMethods 
+} from '@teamnovu/kit-shopware-composables'
+
+export default defineComponent({
+  setup() {
+    // Query products
+    const { data: products, isLoading } = useReadProductListingQuery('category-seo-url')
+    
+    // Manage cart
+    const { data: cart } = useReadCartQuery()
+    const addToCart = useAddLineItemMutation()
+    
+    // Checkout helpers
+    const { paymentMethods, setPaymentMethod } = usePaymentMethods()
+    
+    return {
+      products,
+      isLoading,
+      cart,
+      addToCart,
+      paymentMethods,
+      setPaymentMethod
+    }
+  }
+})
+```
+
+## Setup & Configuration
+
+### 1. Client Injection
+
+Provide the Shopware client to your Vue app:
+
+```typescript
+import { createApp } from 'vue'
+import { ShopwareClient } from '@teamnovu/kit-shopware-api-client'
+import { provideShopwareQueryClient } from '@teamnovu/kit-shopware-composables'
+
+const app = createApp(App)
+
+const client = new ShopwareClient({
+  baseURL: 'https://your-shopware-store.com',
+  apiKey: 'your-api-key'
+})
+
+provideShopwareQueryClient(client)
+app.mount('#app')
+```
+
+### 2. TanStack Query Setup
+
+Install and configure TanStack Query:
+
+```bash
+npm install @tanstack/vue-query
+```
+
+```typescript
+import { VueQueryPlugin } from '@tanstack/vue-query'
+
+app.use(VueQueryPlugin)
+```
+
+## Query Composables
+
+### Product Queries
+
+#### useReadCompactProductListingQuery
+Query products by category or listing criteria:
+
+```typescript
+const { data, isLoading, error } = useReadCompactProductListingQuery('category-seo-url', {
+  query: {
+    limit: 20,
+    page: 1,
+    'filter[price][gte]': 10
+  }
+})
+```
+
+#### useReadCustomProductDetailQuery
+Get detailed product information:
+
+```typescript
+const { data: product } = useReadCustomProductDetailQuery('product-seo-url')
+```
+
+#### useReadCategoryListQuery
+Fetch category navigation:
+
+```typescript
+const { data: categories } = useReadCategoryListQuery()
+```
+
+### Cart Queries & Mutations
+
+#### useReadCartQuery
+Get current cart state:
+
+```typescript
+const { data: cart, refetch } = useReadCartQuery()
+```
+
+#### useAddLineItemMutation
+Add products to cart:
+
+```typescript
+const addToCart = useAddLineItemMutation()
+
+const handleAddToCart = () => {
+  addToCart.mutate({
+    items: [{
+      id: 'product-id',
+      quantity: 1,
+      type: 'product'
+    }]
+  })
+}
+```
+
+#### useUpdateLineItemMutation
+Update cart item quantities:
+
+```typescript
+const updateItem = useUpdateLineItemMutation()
+
+updateItem.mutate({
+  items: [{
+    id: 'line-item-id',
+    quantity: 3
+  }]
+})
+```
+
+#### useRemoveLineItemMutation
+Remove items from cart:
+
+```typescript
+const removeItem = useRemoveLineItemMutation()
+
+removeItem.mutate({
+  ids: ['line-item-id']
+})
+```
+
+### Customer Queries & Mutations
+
+#### useReadCustomerQuery
+Get current customer data:
+
+```typescript
+const { data: customer } = useReadCustomerQuery()
+```
+
+#### useLoginCustomerMutation
+Handle customer login:
+
+```typescript
+const login = useLoginCustomerMutation()
+
+login.mutate({
+  email: 'user@example.com',
+  password: 'password'
+})
+```
+
+### Address Management
+
+#### useListAddressQuery
+Fetch customer addresses:
+
+```typescript
+const { data: addresses } = useListAddressQuery()
+```
+
+### Context & Settings
+
+#### useReadContextQuery
+Get current store context (currency, language, etc.):
+
+```typescript
+const { data: context } = useReadContextQuery()
+```
+
+#### useUpdateContextMutation
+Update store context:
+
+```typescript
+const updateContext = useUpdateContextMutation()
+
+updateContext.mutate({
+  currencyId: 'eur-currency-id',
+  languageId: 'en-language-id'
+})
+```
+
+## Helper Composables
+
+### Checkout Helpers
+
+#### usePaymentMethods
+Manage payment methods:
+
+```typescript
+const {
+  paymentMethods,      // Available payment methods
+  activePaymentMethod, // Currently selected method
+  setPaymentMethod,    // Function to change method
+  isSaving            // Loading state
+} = usePaymentMethods()
+```
+
+#### useShippingMethods
+Manage shipping methods:
+
+```typescript
+const {
+  shippingMethods,
+  activeShippingMethod,
+  setShippingMethod,
+  isSaving
+} = useShippingMethods()
+```
+
+#### useAddresses
+Manage customer addresses:
+
+```typescript
+const {
+  addresses,
+  billingAddress,
+  shippingAddress,
+  setBillingAddress,
+  setShippingAddress,
+  isSaving
+} = useAddresses()
+```
+
+### Product Helpers
+
+#### useProductPrice
+Calculate product pricing:
+
+```typescript
+const { 
+  price,          // Calculated price object
+  displayPrice,   // Formatted display price
+  wasPrice,       // Original price (if on sale)
+  percentage      // Discount percentage
+} = useProductPrice(product, quantity)
+```
+
+#### useProductVariantForOptions
+Handle product variants:
+
+```typescript
+const {
+  variant,        // Selected variant
+  options,        // Available options
+  selectOption    // Function to select option
+} = useProductVariantForOptions(product, selectedOptions)
+```
+
+### General Helpers
+
+#### usePagination
+Handle paginated results:
+
+```typescript
+const {
+  page,
+  limit,
+  total,
+  totalPages,
+  nextPage,
+  prevPage,
+  goToPage
+} = usePagination(initialPage, initialLimit)
+```
+
+#### useSeoUrl
+Handle SEO URL transformations:
+
+```typescript
+const { seoUrl, canonicalUrl } = useSeoUrl(path)
+```
+
+#### useIsLoggedIn
+Check authentication status:
+
+```typescript
+const { isLoggedIn, customer } = useIsLoggedIn()
+```
+
+## Utility Functions
+
+### useOptimistic
+Handle optimistic updates:
+
+```typescript
+const { 
+  optimisticValue,
+  updateOptimistic 
+} = useOptimistic(initialValue)
+```
+
+### unrefOptions
+Utility for unreferencing reactive options:
+
+```typescript
+const unrefdOptions = unrefOptions(maybeReactiveOptions)
+```
+
+## Development Setup
+
+### Docker Environment
+
+The package includes a complete Docker setup for Shopware development:
+
+```bash
+# Generate API types
+npm run gen-types
+
+# Start development environment
+cd docker && docker-compose up
+```
+
+### Type Generation
+
+Generate TypeScript types from your Shopware instance:
+
+```bash
+npm run gen-types
+```
+
+This will:
+1. Fetch the OpenAPI schema from your Shopware store
+2. Generate TypeScript types in `api-types/`
+3. Update operation definitions
+
+## Best Practices
+
+### Query Keys
+Query keys are automatically generated and cached. Use the provided key factories for consistency:
+
+```typescript
+import { productKeys, cartKeys, customerKeys } from '@teamnovu/kit-shopware-composables'
+
+// Access query keys for manual cache management
+queryClient.invalidateQueries(productKeys.lists())
+queryClient.setQueryData(cartKeys.get(), newCartData)
+```
+
+### Error Handling
+Handle errors consistently across queries:
+
+```typescript
+const { data, error, isError } = useReadProductListingQuery('category')
+
+if (isError && error instanceof ShopwareApiError) {
+  console.error('Shopware API Error:', error.status, error.response)
+}
+```
+
+### Loading States
+Leverage TanStack Query's built-in loading states:
+
+```typescript
+const { data, isLoading, isFetching, isStale } = useReadCartQuery()
+
+// isLoading: First load
+// isFetching: Any fetch (including background refetch)
+// isStale: Data is outdated
+```
+
+## Integration Examples
+
+### E-commerce Product List
+
+```vue
+<template>
+  <div>
+    <div v-if="isLoading">Loading...</div>
+    <div v-else-if="error">Error: {{ error.message }}</div>
+    <div v-else>
+      <ProductCard 
+        v-for="product in products?.elements" 
+        :key="product.id"
+        :product="product"
+        @add-to-cart="handleAddToCart"
+      />
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { useReadCompactProductListingQuery, useAddLineItemMutation } from '@teamnovu/kit-shopware-composables'
+
+const { data: products, isLoading, error } = useReadCompactProductListingQuery('category-seo-url')
+const addToCart = useAddLineItemMutation()
+
+const handleAddToCart = (productId) => {
+  addToCart.mutate({
+    items: [{ id: productId, quantity: 1, type: 'product' }]
+  })
+}
+</script>
+```
+
+### Checkout Flow
+
+```vue
+<script setup>
+import { 
+  useReadCartQuery,
+  usePaymentMethods,
+  useShippingMethods,
+  useCheckout 
+} from '@teamnovu/kit-shopware-composables'
+
+const { data: cart } = useReadCartQuery()
+const { paymentMethods, setPaymentMethod } = usePaymentMethods()
+const { shippingMethods, setShippingMethod } = useShippingMethods()
+const { checkout, isCheckingOut } = useCheckout()
+
+const handleCheckout = async () => {
+  try {
+    const order = await checkout()
+    // Handle successful checkout
+  } catch (error) {
+    // Handle checkout error
+  }
+}
+</script>
+```

package/docs/info.json

@@ -0,0 +1,3 @@
+{
+    "name": "🛍️ Shopware Composables"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamnovu/kit-shopware-composables",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "A collection of composables for the Shopware API",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",
@@ -9,6 +9,9 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs"
+    },
+    "./operations": {
+      "types": "./dist/types/operations.d.ts"
     }
   },
   "peerDependencies": {
@@ -24,6 +27,7 @@
   "author": "Elias Bernhaut",
   "homepage": "https://kit.novu.ch/packages/shopware-composables/",
   "dependencies": {
+    "@vueuse/core": "^13.3.0",
     "vite": "^6.2.5"
   },
   "devDependencies": {

package/src/helpers/checkout/index.ts

@@ -0,0 +1,5 @@
+export * from './useAddresses'
+export * from './useOrderDetails'
+export * from './useOrderPayment'
+export * from './usePaymentMethods'
+export * from './useShippingMethods'

package/src/helpers/checkout/useAddresses.ts

@@ -0,0 +1,57 @@
+import { Schemas } from '#store-types'
+import { until } from '@vueuse/core'
+import { computed } from 'vue'
+import { useListAddressQuery } from '../../query/address/useListAddressQuery'
+import { useReadContextQuery } from '../../query/context/useReadContextQuery'
+import { useUpdateContextMutation } from '../../query/context/useUpdateContextMutation'
+
+export function useCheckoutAddresses() {
+  const contextUpdateMutation = useUpdateContextMutation()
+
+  const contextQuery = useReadContextQuery()
+  const addressListQuery = useListAddressQuery()
+
+  const isSaving = computed(() => contextQuery.isFetching.value || contextUpdateMutation.isPending.value)
+
+  const setBillingAddress = async (address: Schemas['CustomerAddress']) => {
+    await contextUpdateMutation.mutateAsync({
+      billingAddressId: address.id,
+    })
+
+    await until(isSaving).toBe(false)
+  }
+
+  const setShippingAddress = async (address: Schemas['CustomerAddress']) => {
+    await contextUpdateMutation.mutateAsync({
+      shippingAddressId: address.id,
+    })
+
+    await until(isSaving).toBe(false)
+  }
+
+  const activeBillingAddress = computed(() => contextQuery.data.value?.customer?.activeBillingAddress)
+  const activeShippingAddress = computed(() => contextQuery.data.value?.customer?.activeShippingAddress)
+
+  const inactiveBillingAddresses = computed(() =>
+    addressListQuery.data.value?.elements.filter(
+      address => address.id !== activeBillingAddress.value?.id,
+    ) ?? [])
+
+  const inactiveShippingAddresses = computed(() =>
+    addressListQuery.data.value?.elements.filter(
+      address => address.id !== activeBillingAddress.value?.id,
+    ) ?? [])
+
+  return {
+    contextUpdateMutation,
+    contextQuery,
+    addressListQuery,
+    setBillingAddress,
+    setShippingAddress,
+    isSaving,
+    activeBillingAddress,
+    activeShippingAddress,
+    inactiveBillingAddresses,
+    inactiveShippingAddresses,
+  }
+}

package/src/helpers/checkout/useOrderDetails.ts

@@ -0,0 +1,94 @@
+import type { MaybeRef } from 'vue'
+import { computed, unref } from 'vue'
+import { useReadOrderQuery } from '../../query/order'
+import { Schemas } from '../../query/types'
+
+export function useOrderDetails(
+  orderId: MaybeRef<string>,
+  criteria?: Schemas['Criteria'],
+) {
+  // Create reactive order query options
+  const orderQueryOptions = computed(() => {
+    const id = unref(orderId)
+    if (!id) return undefined
+
+    return {
+      body: {
+        filter: [
+          {
+            type: 'equals',
+            field: 'id',
+            value: id,
+          },
+        ],
+        ...criteria,
+        checkPromotion: true,
+      } as Schemas['Criteria'],
+    }
+  })
+
+  // Create order query
+  const orderQuery = useReadOrderQuery(orderQueryOptions.value)
+
+  // Computed properties based on order data
+  const order = computed(() => orderQuery.data?.value?.orders?.elements?.[0])
+
+  const paymentChangeableList = computed(() => {
+    return orderQuery.data?.value?.paymentChangeable || {}
+  })
+
+  const status = computed(() => order.value?.stateMachineState?.translated?.name)
+  const statusTechnicalName = computed(() => order.value?.stateMachineState?.technicalName)
+  const total = computed(() => order.value?.price?.totalPrice)
+  const subtotal = computed(() => order.value?.price?.positionPrice)
+  const shippingCosts = computed(() => order.value?.shippingTotal)
+
+  const personalDetails = computed(() => ({
+    email: order.value?.orderCustomer?.email,
+    firstName: order.value?.orderCustomer?.firstName,
+    lastName: order.value?.orderCustomer?.lastName,
+  }))
+
+  const billingAddress = computed(() =>
+    order.value?.addresses?.find(
+      ({ id }: { id: string }) => id === order.value?.billingAddressId,
+    ))
+
+  const shippingAddress = computed(
+    () => order.value?.deliveries?.[0]?.shippingOrderAddress,
+  )
+
+  const paymentMethod = computed(() => {
+    const transactions = order.value?.transactions
+    if (!transactions?.length) return undefined
+    return transactions.at(-1)?.paymentMethod
+  })
+
+  const shippingMethod = computed(() => {
+    const deliveries = order.value?.deliveries
+    if (!deliveries?.length) return undefined
+    return deliveries.at(-1)?.shippingMethod
+  })
+
+  const paymentChangeable = computed(() => {
+    const id = unref(orderId)
+    return paymentChangeableList.value?.[id] ?? false
+  })
+
+  return {
+    order,
+    status,
+    statusTechnicalName,
+    total,
+    subtotal,
+    shippingCosts,
+    shippingAddress,
+    billingAddress,
+    personalDetails,
+    shippingMethod,
+    paymentMethod,
+    paymentChangeable,
+    orderQuery,
+    orderSetPaymentMutation,
+  }
+}

package/src/helpers/checkout/useOrderPayment.ts

@@ -0,0 +1,28 @@
+import type { MaybeRef } from 'vue'
+import { computed, unref } from 'vue'
+import { Schemas } from '../../query/types'
+
+export function useOrderPayment(
+  order: MaybeRef<Schemas['Order'] | null | undefined>,
+) {
+  const activeTransaction = computed(() =>
+    unref(order)?.transactions?.find(t => t.paymentMethod?.active === true))
+
+  const paymentMethod = computed(() => activeTransaction.value?.paymentMethod)
+  const state = computed(() => activeTransaction.value?.stateMachineState)
+
+  const isAsynchronous = computed(
+    () =>
+      // @ts-expect-error - This property does not seem to be declared in the typescript types
+      activeTransaction.value?.paymentMethod?.asynchronous
+      && activeTransaction.value?.paymentMethod?.afterOrderEnabled,
+  )
+
+  return {
+    isAsynchronous,
+    activeTransaction,
+    state,
+    paymentMethod,
+  }
+}
+

package/src/helpers/checkout/usePaymentMethods.ts

@@ -0,0 +1,35 @@
+import { computed } from 'vue'
+import { useReadPaymentMethodQuery } from '../../query'
+import { useReadContextQuery } from '../../query/context/useReadContextQuery'
+import { useUpdateContextMutation } from '../../query/context/useUpdateContextMutation'
+
+export function usePaymentMethods() {
+  const contextQuery = useReadContextQuery()
+  const contextUpdateMutation = useUpdateContextMutation()
+  const paymentMethodsQuery = useReadPaymentMethodQuery({
+    query: {
+      onlyActive: true,
+    },
+  })
+
+  const isSaving = computed(() => contextUpdateMutation.isPending.value)
+
+  const setPaymentMethod = async (paymentMethodId: string) => {
+    return contextUpdateMutation.mutateAsync({
+      paymentMethodId,
+    })
+  }
+
+  const activePaymentMethod = computed(() => contextQuery.data?.value?.paymentMethod)
+  const paymentMethods = computed(() => paymentMethodsQuery.data?.value?.elements)
+
+  return {
+    contextUpdateMutation,
+    contextQuery,
+    paymentMethodsQuery,
+    activePaymentMethod,
+    setPaymentMethod,
+    isSaving,
+    paymentMethods,
+  }
+}