feat(docs): add Storefront Data SKILL

Author: KaiUweCZE

libs/storefront-data/.codex/skills/storefront-data-auth/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: storefront-data-auth
+description: Customer authentication integration for @techsio/storefront-data. Use when implementing auth state, login/register/logout mutations, customer profile updates, and auth-related cache invalidation with Medusa.
+---
+
+# Storefront Data Auth
+
+Implement auth through the auth module to keep session and cache invalidation coherent.
+
+## Workflow
+
+1. Create service with `createMedusaAuthService(sdk)`.
+2. Create hooks with `createAuthHooks` and shared namespace.
+3. Optionally define `invalidateOnAuthChange` for custom cross-domain keys.
+4. Use `useAuth` for session state and mutation hooks for auth actions.
+
+## Example
+
+```ts
+import {
+  createAuthHooks,
+  createAuthQueryKeys,
+  createMedusaAuthService,
+} from "@techsio/storefront-data"
+import { cacheConfig, sdk, STOREFRONT_NAMESPACE } from "@/lib/storefront-data/shared"
+
+const authService = createMedusaAuthService(sdk)
+const authQueryKeys = createAuthQueryKeys(STOREFRONT_NAMESPACE)
+
+export const authHooks = createAuthHooks({
+  service: authService,
+  queryKeys: authQueryKeys,
+  cacheConfig,
+  invalidateOnAuthChange: {
+    includeDefaults: true,
+  },
+})
+```
+
+## Returned Hooks
+
+- `useAuth`, `useSuspenseAuth`
+- `useLogin`, `useRegister`, `useLogout`
+- `useCreateCustomer`, `useUpdateCustomer`, `useRefreshAuth`
+
+## Rules
+
+- Prefer `createMedusaAuthService` registration flow: register -> login -> customer create -> refresh.
+- Keep `useAuth` query `retry: false` behavior for auth-state checks.
+- On logout, assume auth cache is removed; refresh dependent modules after logout redirect.
+- Use `userData` cache strategy for auth profile data.

libs/storefront-data/.codex/skills/storefront-data-cart/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: storefront-data-cart
+description: Cart lifecycle integration for @techsio/storefront-data. Use when implementing cart retrieval/creation, line item mutations, address updates, cart transfer/complete flow, and cart storage persistence in storefront apps.
+---
+
+# Storefront Data Cart
+
+Implement cart behavior with the cart factory to preserve auto-create, region sync, and cache semantics.
+
+## Workflow
+
+1. Create `cartStorage` for persistent cart id.
+2. Create service with `createMedusaCartService(sdk)`.
+3. Create hooks with `createCartHooks` and pass `cartStorage`.
+4. Use `useCart` as cart source of truth in UI.
+5. Use provided mutations (`useAddLineItem`, `useUpdateCartAddress`, etc.) for all writes.
+
+## Example
+
+```ts
+import {
+  createCartHooks,
+  createCartQueryKeys,
+  createMedusaCartService,
+} from "@techsio/storefront-data"
+import { cacheConfig, sdk, STOREFRONT_NAMESPACE } from "@/lib/storefront-data/shared"
+
+const cartStorage = {
+  getCartId: () => localStorage.getItem("cart_id"),
+  setCartId: (id: string) => localStorage.setItem("cart_id", id),
+  clearCartId: () => localStorage.removeItem("cart_id"),
+}
+
+const cartService = createMedusaCartService(sdk)
+const cartQueryKeys = createCartQueryKeys(STOREFRONT_NAMESPACE)
+
+export const cartHooks = createCartHooks({
+  service: cartService,
+  queryKeys: cartQueryKeys,
+  cacheConfig,
+  cartStorage,
+  requireRegion: true,
+})
+```
+
+## Returned Hooks
+
+- `useCart`, `useSuspenseCart`
+- `useCreateCart`, `useUpdateCart`, `useUpdateCartAddress`
+- `useAddLineItem`, `useUpdateLineItem`, `useRemoveLineItem`
+- `useTransferCart`, `useCompleteCart`
+- `usePrefetchCart`
+
+## Rules
+
+- Keep `autoCreate` enabled unless app explicitly requires manual cart creation.
+- Pass region (`region_id`) or provide `RegionProvider` when `requireRegion` is true.
+- Use address normalization/validation callbacks for checkout-safe payloads.
+- Decide explicitly whether to clear storage after completion via `clearCartOnSuccess` option.
+- Use `realtime` cache strategy for cart data.

libs/storefront-data/.codex/skills/storefront-data-categories/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: storefront-data-categories
+description: Category list/detail integration for @techsio/storefront-data. Use when implementing product category hooks, Medusa category service mapping, and category query key strategy in storefront apps.
+---
+
+# Storefront Data Categories
+
+Implement category data through the module factory to preserve pagination and cache behavior.
+
+## Workflow
+
+1. Create service with `createMedusaCategoryService`.
+2. Configure optional list/detail query normalization and transforms.
+3. Create hooks with `createCategoryHooks` and shared namespace.
+4. Use built-in prefetch hooks for menu/navigation UX.
+
+## Example
+
+```ts
+import {
+  createCategoryHooks,
+  createCategoryQueryKeys,
+  createMedusaCategoryService,
+} from "@techsio/storefront-data"
+import { cacheConfig, sdk, STOREFRONT_NAMESPACE } from "@/lib/storefront-data/shared"
+
+const categoryService = createMedusaCategoryService(sdk, {
+  defaultListFields: "id,name,handle,parent_category_id",
+  defaultDetailFields: "id,name,handle,parent_category_id",
+})
+
+const categoryQueryKeys = createCategoryQueryKeys(STOREFRONT_NAMESPACE)
+
+export const categoryHooks = createCategoryHooks({
+  service: categoryService,
+  queryKeys: categoryQueryKeys,
+  cacheConfig,
+})
+```
+
+## Returned Hooks
+
+- `useCategories`, `useSuspenseCategories`
+- `useCategory`, `useSuspenseCategory`
+- `usePrefetchCategories`, `usePrefetchCategory`
+
+## Rules
+
+- Keep category cache `static` unless business rules require quicker refresh.
+- Throw early for missing `id` in suspense detail usage.
+- Keep query-key params normalized and deterministic.

libs/storefront-data/.codex/skills/storefront-data-checkout/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: storefront-data-checkout
+description: Checkout shipping/payment integration for @techsio/storefront-data. Use when implementing shipping option selection, calculated shipping prices, payment provider loading, and payment session initiation tied to cart state.
+---
+
+# Storefront Data Checkout
+
+Wire checkout with cart hooks so shipping/payment mutations keep cart cache consistent.
+
+## Workflow
+
+1. Create checkout service with `createMedusaCheckoutService(sdk)`.
+2. Create hooks with `createCheckoutHooks`.
+3. Pass `cartQueryKeys` from cart module to sync/refresh cart cache after mutations.
+4. Use shipping hook first, then payment hook.
+
+## Example
+
+```ts
+import {
+  createCheckoutHooks,
+  createCheckoutQueryKeys,
+  createMedusaCheckoutService,
+} from "@techsio/storefront-data"
+import { cartQueryKeys } from "@/lib/storefront-data/cart"
+import { cacheConfig, sdk, STOREFRONT_NAMESPACE } from "@/lib/storefront-data/shared"
+
+const checkoutService = createMedusaCheckoutService(sdk)
+const checkoutQueryKeys = createCheckoutQueryKeys(STOREFRONT_NAMESPACE)
+
+export const checkoutHooks = createCheckoutHooks({
+  service: checkoutService,
+  queryKeys: checkoutQueryKeys,
+  cartQueryKeys,
+  cacheConfig,
+})
+```
+
+## Returned Hooks
+
+- `useCheckoutShipping`, `useSuspenseCheckoutShipping`
+- `useCheckoutPayment`, `useSuspenseCheckoutPayment`
+- `getPaymentProvidersQueryOptions`, `fetchPaymentProviders`
+
+## Rules
+
+- Require `cartId` for shipping mutation and payment initiation.
+- Use shipping method before payment session; `canInitiatePayment` depends on it.
+- Use `cacheKey` in shipping queries when option visibility depends on external checkout state.
+- Keep payment providers on `semiStatic` cache; shipping options/prices on `realtime` cache.

libs/storefront-data/.codex/skills/storefront-data-client/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: storefront-data-client
+description: Client-side setup for @techsio/storefront-data. Use when adding StorefrontDataProvider, browser QueryClient lifecycle, or client hydration boundaries in a React/Next.js storefront app.
+---
+
+# Storefront Data Client
+
+Implement the client provider once and reuse it in all routes.
+
+## Workflow
+
+1. Create `providers.tsx` client component in app.
+2. Wrap tree with `StorefrontDataProvider`.
+3. Optionally pass `clientConfig` only on first initialization.
+4. Keep provider in client boundary (`"use client"`).
+
+## Example
+
+```tsx
+"use client"
+
+import type { ReactNode } from "react"
+import { StorefrontDataProvider } from "@techsio/storefront-data/client"
+
+export function Providers({ children }: { children: ReactNode }) {
+  return <StorefrontDataProvider>{children}</StorefrontDataProvider>
+}
+```
+
+## Advanced
+
+Use custom query client config only when needed:
+
+```tsx
+<StorefrontDataProvider
+  clientConfig={{
+    defaultOptions: {
+      queries: { retry: false },
+    },
+  }}
+>
+  {children}
+</StorefrontDataProvider>
+```
+
+## Rules
+
+- Do not create multiple browser singletons manually; prefer `StorefrontDataProvider`.
+- Do not place `StorefrontDataProvider` in server component files.
+- If you need isolated cache (tests/storybook), pass explicit `client` prop.

libs/storefront-data/.codex/skills/storefront-data-collections/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: storefront-data-collections
+description: Collection list/detail integration for @techsio/storefront-data. Use when wiring collection hooks, Medusa collection service transforms, and collection prefetch behavior in a storefront app.
+---
+
+# Storefront Data Collections
+
+Use the collection factory to keep list/detail behavior and cache policies consistent.
+
+## Workflow
+
+1. Create service with `createMedusaCollectionService`.
+2. Optionally normalize list/detail queries and map Medusa payload to app entity.
+3. Create hooks via `createCollectionHooks`.
+4. Use prefetch hooks for list/detail route transitions.
+
+## Example
+
+```ts
+import {
+  createCollectionHooks,
+  createCollectionQueryKeys,
+  createMedusaCollectionService,
+} from "@techsio/storefront-data"
+import { cacheConfig, sdk, STOREFRONT_NAMESPACE } from "@/lib/storefront-data/shared"
+
+const collectionService = createMedusaCollectionService(sdk, {
+  defaultListFields: "id,title,handle",
+  defaultDetailFields: "id,title,handle,metadata",
+})
+
+const collectionQueryKeys = createCollectionQueryKeys(
+  STOREFRONT_NAMESPACE
+)
+
+export const collectionHooks = createCollectionHooks({
+  service: collectionService,
+  queryKeys: collectionQueryKeys,
+  cacheConfig,
+})
+```
+
+## Returned Hooks
+
+- `useCollections`, `useSuspenseCollections`
+- `useCollection`, `useSuspenseCollection`
+- `usePrefetchCollections`, `usePrefetchCollection`
+
+## Rules
+
+- Use `static` cache strategy as default for collections.
+- Require `id` for detail suspense hook.
+- Keep `enabled` and UI flags out of API payload/query keys.

libs/storefront-data/.codex/skills/storefront-data-customers/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: storefront-data-customers
+description: Customer profile/address integration for @techsio/storefront-data. Use when implementing customer address CRUD, profile updates, address input normalization/validation, and auth profile cache synchronization.
+---
+
+# Storefront Data Customers
+
+Use customer hooks for account profile + address book operations.
+
+## Workflow
+
+1. Create service with `createMedusaCustomerService(sdk)`.
+2. Create hooks with `createCustomerHooks`.
+3. Pass `authQueryKeys.customer` when custom auth keys are used.
+4. Add input normalization and validation callbacks for address write safety.
+
+## Example
+
+```ts
+import {
+  createCustomerHooks,
+  createCustomerQueryKeys,
+  createMedusaCustomerService,
+} from "@techsio/storefront-data"
+import { authQueryKeys } from "@/lib/storefront-data/auth"
+import { cacheConfig, sdk, STOREFRONT_NAMESPACE } from "@/lib/storefront-data/shared"
+
+const customerService = createMedusaCustomerService(sdk)
+const customerQueryKeys = createCustomerQueryKeys(STOREFRONT_NAMESPACE)
+
+export const customerHooks = createCustomerHooks({
+  service: customerService,
+  queryKeys: customerQueryKeys,
+  authQueryKeys,
+  cacheConfig,
+  validateCreateAddressInput: (input) => {
+    if (!input.first_name || !input.address_1 || !input.country_code) {
+      return "Missing required address fields"
+    }
+    return null
+  },
+})
+```
+
+## Returned Hooks
+
+- `useCustomerAddresses`, `useSuspenseCustomerAddresses`
+- `useCreateCustomerAddress`, `useUpdateCustomerAddress`, `useDeleteCustomerAddress`
+- `useUpdateCustomer`
+
+## Rules
+
+- In `useUpdateCustomerAddress`, provide `addressId` and remove it from payload mapper.
+- Keep profile/address data on `userData` cache strategy.
+- Invalidate both customer profile and auth customer keys after profile updates.