@akinon/projectzero 1.96.0-snapshot-ZERO-35861-20250908151109 → 1.96.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @akinon/projectzero
 
-## 1.96.0-snapshot-ZERO-35861-20250908151109
+## 1.96.0
 
 ## 1.95.0
 

package/app-template/.github/instructions/checkout.instructions.md

@@ -0,0 +1,678 @@
+---
+applyTo: 'src/app/**/checkout/**|src/views/checkout/**|src/components/**/checkout/**'
+---
+
+# Project Zero Checkout - Developer Instructions
+
+## Overview
+
+The checkout functionality in Project Zero Next.js is a multi-step e-commerce flow that handles user authentication, shipping, payment, and order completion. It's built with Redux state management, RTK Query for API calls, and supports various payment plugins.
+
+## Checkout Architecture
+
+### Route Structure
+
+```
+/[commerce]/[locale]/[currency]/orders/checkout/
+```
+
+- **Main Page**: `src/app/[commerce]/[locale]/[currency]/orders/checkout/page.tsx`
+- **Route Constants**: Defined in `src/routes/index.ts` as `ROUTES.CHECKOUT`
+
+### Core Components
+
+```
+src/views/checkout/
+├── auth.tsx                    # Authentication/Guest checkout
+├── step-list.tsx              # Progress indicator
+├── index.tsx                  # Summary component
+└── steps/
+    ├── shipping/              # Shipping step components
+    └── payment/               # Payment step components
+```
+
+### State Management
+
+**Redux Store**: `checkout` slice handles multi-step flow state
+
+```tsx
+import { useAppSelector, useAppDispatch } from '@akinon/next/redux/hooks';
+import { setCurrentStep, resetCheckoutState } from '@akinon/next/redux/reducers/checkout';
+
+// Access checkout state
+const { steps, preOrder } = useAppSelector((state: RootState) => state.checkout);
+```
+
+## Checkout Flow Steps
+
+### 1. Authentication Step
+
+**Template Detection**: `checkoutData?.template_name === 'orders/index.html'`
+
+**Components Used**:
+- `CheckoutAuth` - Main authentication wrapper
+- `Login` - Existing user login
+- `GuestLogin` - Guest checkout option
+
+**Key Features**:
+- NextAuth.js integration with `useSession()`
+- Callback URL handling for post-login redirect
+- Guest checkout with email/phone validation
+
+```tsx
+// Authentication check pattern
+const { status } = useSession();
+
+useEffect(() => {
+  if (status === 'authenticated') {
+    dispatch(api.util.invalidateTags(['Checkout']));
+  } else if (status === 'unauthenticated') {
+    router.replace(ROUTES.CHECKOUT + `?callbackUrl=${ROUTES.CHECKOUT}`);
+  }
+}, [status]);
+```
+
+### 2. Shipping Step
+
+**When Active**: `steps.current === CheckoutStep.Shipping`
+
+**Key APIs**:
+- `setDeliveryOption` - Select delivery method
+- `setAddresses` - Set billing/shipping addresses
+- `setShippingOption` - Choose shipping method
+
+**Auto-progression**: Automatically moves to payment when shipping is completed
+
+```tsx
+useEffect(() => {
+  if (steps.shipping.completed && !initialStepChanged.current) {
+    dispatch(setCurrentStep(CheckoutStep.Payment));
+    initialStepChanged.current = true;
+  }
+}, [steps.shipping.completed]);
+```
+
+### 3. Payment Step
+
+**When Active**: `steps.current === CheckoutStep.Payment`
+
+**Key APIs**:
+- `setPaymentOption` - Select payment method
+- `setInstallmentOption` - Choose installments
+- `completeCreditCardPayment` - Process card payments
+- Various plugin-specific payment completions
+
+**Plugin Integration**: Extensive payment plugin support via `PluginModule`
+
+## API Integration
+
+### Core Hooks
+
+```tsx
+// Primary checkout data fetching
+const { data: checkoutData, isFetching, isError, refetch } = useFetchCheckoutQuery(null);
+
+// State reset on page load
+const { data: indexData, isLoading } = useResetCheckoutStateQuery(null);
+```
+
+### Mutation Patterns
+
+**All checkout mutations follow this pattern**:
+
+```tsx
+const [mutationFn] = useMutationHook();
+
+// With loading state management
+async onQueryStarted(arg, { dispatch, queryFulfilled }) {
+  dispatch(setShippingStepBusy(true)); // or setPaymentStepBusy
+  await queryFulfilled;
+  dispatch(setShippingStepBusy(false));
+}
+```
+
+### Error Handling
+
+**Standard error UI pattern**:
+
+```tsx
+if (isResetStateLoading || isFetching || isError) {
+  return (
+    <div className="flex flex-col items-center justify-center h-80">
+      {isResetStateLoading || isFetching ? (
+        <LoaderSpinner />
+      ) : (
+        <>
+          <div>{t('checkout.error.title')}</div>
+          <div className="mt-5">
+            <Button onClick={refetchCheckout}>
+              {t('checkout.error.button')}
+            </Button>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+```
+
+## Plugin System
+
+### Core Plugin Architecture
+
+**Plugin Wrapper**: All checkout features use `PluginModule` for extensibility
+
+```tsx
+import PluginModule, { Component } from '@akinon/next/components/plugin-module';
+
+// Conditional plugin rendering
+<PluginModule component={Component.PluginName} props={...} />
+```
+
+### Available Checkout Plugins
+
+**Payment Plugins**:
+- `pz-masterpass` - Masterpass integration
+- `pz-apple-pay` - Apple Pay support (with custom UI override capabilities)
+- `pz-gpay` - Google Pay integration
+- `pz-bkm` - BKM Express payments
+- `pz-saved-card` - Saved card management
+- `pz-credit-payment` - Credit/installment payments
+- `pz-flow-payment` - Flow payment gateway
+- `pz-tabby-extension` - Tabby BNPL (MENA)
+- `pz-tamara-extension` - Tamara BNPL (MENA)
+
+**Checkout Enhancement Plugins**:
+- `pz-one-click-checkout` - Simplified one-click payments
+- `pz-checkout-gift-pack` - Gift wrapping options
+- `pz-click-collect` - Store pickup options
+- `pz-otp` - OTP verification
+- `pz-pay-on-delivery` - Cash on delivery
+
+### Plugin Integration Example
+
+```tsx
+// Masterpass integration in checkout
+<PluginModule component={Component.MasterpassProvider}>
+  <PluginModule component={Component.MasterpassDeleteConfirmationModal} />
+  <PluginModule component={Component.MasterpassOtpModal} />
+  <PluginModule component={Component.MasterpassLinkModal} />
+  
+  {/* Your checkout content */}
+</PluginModule>
+```
+
+**Apple Pay Implementation**:
+
+There are two ways to implement Apple Pay:
+
+### Option 1: Full Plugin (Recommended)
+Use the `pz-apple-pay` package for complete Apple Pay functionality:
+
+**Quick Setup** (Recommended):
+```bash
+npx @akinon/projectzero@latest --plugins
+```
+
+**Manual Setup**:
+
+### Option 2: UI Customization Only
+If you only need to customize the Apple Pay UI, create a custom component:
+
+1. **Create the Apple Pay component**: Create `src/views/checkout/steps/payment/options/apple-pay.tsx`
+2. **Import in payment.tsx**: Add `import ApplePay from './options/apple-pay';`
+3. **Add to PaymentOptionViews**: Add the component to the PaymentOptionViews array
+
+**Implementation Pattern**:
+```tsx
+// In payment.tsx
+import ApplePay from './options/apple-pay';
+
+export const PaymentOptionViews: Array<CheckoutPaymentOption> = [
+  {
+    slug: 'apple-pay-wallet',
+    view: ApplePay
+  }
+];
+```
+
+### Payment UI Customization Patterns
+
+**Apple Pay Component Structure**:
+
+Here's the basic structure for the Apple Pay component that should be placed in `src/views/checkout/steps/payment/options/apple-pay.tsx`:
+
+```tsx
+'use client';
+
+import { checkoutApi } from '@akinon/next/data/client/checkout';
+import { useAppDispatch, useAppSelector } from '@akinon/next/redux/hooks';
+import { Button, Modal } from '@theme/components';
+import { RootState } from '@theme/redux/store';
+import { useState } from 'react';
+import { SubmitHandler, useForm } from 'react-hook-form';
+import { useLocalization } from '@akinon/next/hooks';
+
+export default function ApplePay() {
+  const { handleSubmit } = useForm();
+  const { t } = useLocalization();
+  const { walletPaymentData, preOrder } = useAppSelector(
+    (state: RootState) => state.checkout
+  );
+  
+  const dispatch = useAppDispatch();
+  const [errors, setErrors] = useState(null);
+  const [showConfirmationModal, setShowConfirmationModal] = useState(false);
+
+  const onSubmit: SubmitHandler<null> = async () => {
+    try {
+      // 1. Prepare payment request
+      const request = new PaymentRequest(paymentMethodData, paymentDetails);
+      
+      // 2. Show confirmation modal instead of directly calling request.show()
+      setShowConfirmationModal(true);
+      
+      // 3. Store request for later use
+      window.applePayRequest = request;
+    } catch (error) {
+      setErrors(error);
+    }
+  };
+
+  const handleApplePayConfirm = async () => {
+    setShowConfirmationModal(false);
+    
+    try {
+      const request = window.applePayRequest;
+      
+      // 4. Now trigger the actual Apple Pay flow
+      request.show().then(async (paymentRequestResponse) => {
+        // 5. Handle payment response and API calls
+        // - Call setWalletPaymentPage
+        // - Call setWalletCompletePage  
+        // - Handle success/failure
+        // - Redirect to thank you page
+      });
+    } catch (error) {
+      setErrors(error);
+    }
+  };
+
+  if (!walletPaymentData) {
+    return null;
+  }
+
+  return (
+    <>
+      <form onSubmit={handleSubmit(onSubmit)}>
+        <Button className="!hidden" type="submit"></Button>
+      </form>
+      
+      {/* Custom confirmation modal */}
+      {showConfirmationModal && (
+        <Modal
+          open={showConfirmationModal}
+          setOpen={setShowConfirmationModal}
+        >
+          <div className="p-6">
+            <p>{t('checkout.payment.apple_pay.confirmation_message')}</p>
+            <Button onClick={handleApplePayConfirm}>
+              {t('common.confirm')}
+            </Button>
+          </div>
+        </Modal>
+      )}
+    </>
+  );
+}
+```
+
+**Key Implementation Steps**:
+
+1. **Payment Request Setup**: Create PaymentRequest with proper method data and details
+2. **Confirmation Modal**: Show custom UI before triggering native Apple Pay
+3. **Request Storage**: Store payment request for later use via `window.applePayRequest`
+4. **Payment Flow**: Handle the complete Apple Pay flow with API integrations
+5. **Error Handling**: Implement comprehensive error handling throughout the process
+6. **State Management**: Use Redux for checkout state and payment session management
+
+
+## Form Handling
+
+### Standard Form Pattern
+
+**Use React Hook Form + Yup validation**:
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { yupResolver } from '@hookform/resolvers/yup';
+import * as yup from 'yup';
+
+const schema = (t) => yup.object().shape({
+  email: yup.string().email().required(t('error.required')),
+  phone: yup.string().required(t('error.required'))
+});
+
+const { register, handleSubmit, formState: { errors } } = useForm({
+  resolver: yupResolver(schema(t))
+});
+```
+
+### Guest Login Form Example
+
+```tsx
+const onSubmit = async (data) => {
+  try {
+    await guestLogin(data);
+    // Handle success - usually redirects automatically
+  } catch (error) {
+    // Handle validation errors
+    if (error?.data?.form_errors) {
+      // Set form errors from backend
+    }
+  }
+};
+```
+
+## Internationalization
+
+### Translation Keys
+
+**Checkout-specific translations**: `checkout.json`
+
+```tsx
+import { useLocalization } from '@akinon/next/hooks';
+
+const { t } = useLocalization();
+
+// Common translation patterns
+t('checkout.auth.title')           // "Don't have an account?"
+t('checkout.auth.signup')          // "Sign up"
+t('checkout.auth.guest_checkout')  // "Guest Checkout"
+t('checkout.error.title')          // "Error occurred"
+t('checkout.error.button')         // "Try Again"
+```
+
+### Multi-language Support
+
+**Route structure includes locale**: `/[commerce]/[locale]/[currency]/orders/checkout/`
+
+## Analytics Integration
+
+### GTM/E-commerce Tracking
+
+**Automatic event tracking**:
+
+```tsx
+import { pushAddShippingInfo, pushAddPaymentInfo } from '@theme/utils/gtm';
+
+// Auto-triggered on step completion
+useEffect(() => {
+  if (isSuccess) {
+    const products = checkoutData?.pre_order?.basket?.basketitem_set.map(
+      (basketItem) => ({ ...basketItem.product })
+    );
+    
+    if (steps.current === 'shipping') {
+      pushAddShippingInfo(products);
+    }
+    if (steps.current === 'payment') {
+      pushAddPaymentInfo(products, String(preOrder?.payment_option?.name));
+    }
+  }
+}, [isSuccess, steps, checkoutData, preOrder?.payment_option?.name]);
+```
+
+## Development Guidelines
+
+### Component Structure
+
+**Follow this hierarchy**:
+
+```tsx
+// Page-level component (src/app/.../checkout/page.tsx)
+const Checkout = () => {
+  // 1. Hooks and state
+  const { t } = useLocalization();
+  const { steps, preOrder } = useAppSelector((state) => state.checkout);
+  
+  // 2. API calls
+  const { data: checkoutData } = useFetchCheckoutQuery(null);
+  
+  // 3. Effects for flow control
+  useEffect(() => {
+    // Step progression logic
+  }, [dependencies]);
+  
+  // 4. Early returns for different states
+  if (isAuthRequired) return <CheckoutAuth />;
+  if (isLoading) return <LoaderSpinner />;
+  if (isError) return <ErrorState />;
+  
+  // 5. Main render with plugin wrappers
+  return (
+    <PluginModule component={Component.PaymentProvider}>
+      <CheckoutStepList />
+      <div className="checkout-content">
+        {steps.current === CheckoutStep.Shipping && <ShippingStep />}
+        {steps.current === CheckoutStep.Payment && <PaymentStep />}
+      </div>
+      <Summary />
+    </PluginModule>
+  );
+};
+```
+
+### Dynamic Imports
+
+**Use dynamic imports for step components**:
+
+```tsx
+const CheckoutAuth = useMemo(
+  () => dynamic(() => import('@theme/views/checkout/auth')),
+  []
+);
+```
+
+### State Management Best Practices
+
+**1. Always reset checkout state on unmount**:
+
+```tsx
+useEffect(() => {
+  return () => {
+    dispatch(resetCheckoutState());
+  };
+}, []);
+```
+
+**2. Use step-specific busy states**:
+
+```tsx
+// In mutations
+dispatch(setShippingStepBusy(true));
+// or
+dispatch(setPaymentStepBusy(true));
+```
+
+**3. Handle step progression carefully**:
+
+```tsx
+const initialStepChanged = useRef<boolean>(false);
+
+useEffect(() => {
+  if (shouldProgressToNextStep && !initialStepChanged.current) {
+    dispatch(setCurrentStep(NextStep));
+    initialStepChanged.current = true;
+  }
+}, [shouldProgressToNextStep]);
+```
+
+### Styling Guidelines
+
+**Use TailwindCSS with responsive design**:
+
+```tsx
+<div className="container flex flex-col flex-wrap w-full px-4 md:px-0">
+  <div className="w-full h-fit-content lg:w-2/3">
+    {/* Main content */}
+  </div>
+  <div className="w-full h-fit-content mt-6 lg:w-1/3 lg:pl-8 lg:mt-0">
+    {/* Sidebar */}
+  </div>
+</div>
+```
+
+## Security Considerations
+
+### Authentication
+
+- Always check authentication status before allowing checkout
+- Handle callback URLs properly for post-login redirects
+- Support both authenticated and guest checkout flows
+
+### Data Validation
+
+- Validate all form inputs on both client and server
+- Use proper form validation with Yup schemas
+- Handle backend validation errors gracefully
+
+### Payment Security
+
+- Never store sensitive payment data in frontend state
+- Use secure payment provider integrations
+- Implement proper 3D Secure flows when required
+
+## Testing Guidelines
+
+### Component Testing
+
+**Test checkout flow components**:
+
+```typescript
+// Test authentication flow
+describe('CheckoutAuth', () => {
+  it('redirects authenticated users', () => {
+    // Mock authenticated session
+    // Verify redirect behavior
+  });
+  
+  it('shows guest login for unauthenticated users', () => {
+    // Mock unauthenticated session
+    // Verify guest login form is shown
+  });
+});
+```
+
+### Integration Testing
+
+**Test complete checkout flows**:
+
+```typescript
+describe('Checkout Flow', () => {
+  it('completes guest checkout successfully', async () => {
+    // 1. Add items to basket
+    // 2. Navigate to checkout
+    // 3. Complete guest login
+    // 4. Fill shipping information
+    // 5. Select payment method
+    // 6. Complete order
+  });
+});
+```
+
+## Common Patterns
+
+### Redirect Handling
+
+```tsx
+// Handle API redirects
+if (checkoutData?.redirect_url?.includes('basket')) {
+  router.push(ROUTES.BASKET);
+  return null;
+}
+```
+
+### Plugin Component Patterns
+
+```tsx
+// Conditional plugin usage
+<PluginModule component={Component.PluginName} props={{ data }}>
+  {/* Children components */}
+</PluginModule>
+
+// Multiple plugin modals
+<PluginModule component={Component.MasterpassProvider}>
+  <PluginModule component={Component.MasterpassDeleteConfirmationModal} />
+  <PluginModule component={Component.MasterpassOtpModal} />
+  {/* Main content */}
+</PluginModule>
+```
+
+### Loading State Management
+
+```tsx
+// Standard loading pattern
+if (isResetStateLoading || isFetching || isError) {
+  return (
+    <div className="flex flex-col items-center justify-center h-80">
+      {isResetStateLoading || isFetching ? (
+        <LoaderSpinner />
+      ) : (
+        <ErrorWithRetry onRetry={refetchCheckout} />
+      )}
+    </div>
+  );
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**1. Checkout state not resetting**:
+- Ensure `resetCheckoutState()` is called on component unmount
+- Check if `useResetCheckoutStateQuery` is properly called
+
+**2. Step progression not working**:
+- Verify `initialStepChanged` ref is being used correctly
+- Check step completion conditions in Redux state
+
+**3. Plugin not loading**:
+- Ensure plugin is listed in `src/plugins.js`
+- Verify plugin component is available in `Component` enum
+- Check plugin dependencies in `package.json`
+
+**4. Authentication flow issues**:
+- Check NextAuth configuration
+- Verify callback URLs are properly set
+- Ensure session status is being handled correctly
+
+### Debugging Tips
+
+**1. Redux DevTools**: Monitor checkout state changes
+**2. Network Tab**: Check API calls and responses
+**3. Console Logs**: Add logging for step transitions
+**4. Plugin Logging**: Enable plugin-specific debug logs
+
+## Performance Considerations
+
+### Code Splitting
+
+- Use dynamic imports for step components
+- Lazy load payment provider components
+- Split plugin bundles appropriately
+
+### API Optimization
+
+- Use RTK Query caching effectively
+- Invalidate tags only when necessary
+- Implement proper loading states
+
+### Bundle Size
+
+- Tree-shake unused plugins
+- Optimize payment provider scripts
+- Monitor bundle size with webpack-bundle-analyzer
+
+When working on checkout functionality, always consider the complete user journey, handle edge cases gracefully, and ensure compatibility with the extensive plugin ecosystem.

package/app-template/.github/instructions/settings.instructions.md

@@ -0,0 +1,338 @@
+# Settings.js Configuration Instructions
+
+This file is the main configuration file for the ProjectZero Next.js application. All customizable settings are defined here.
+
+## 📋 Table of Contents
+
+- [Basic Structure](#basic-structure)
+- [Available Settings](#available-settings)
+- [Detailed Explanations](#detailed-explanations)
+- [Example Configuration](#example-configuration)
+- [Plugin Configuration](#plugin-configuration)
+- [Important Notes](#important-notes)
+
+## Basic Structure
+
+```javascript
+/** @type {import('@akinon/next/types').Settings} */
+module.exports = {
+  // Settings are defined here
+};
+```
+
+## Available Settings
+
+### 1. 🌐 Web Vitals
+```javascript
+webVitals: {
+  enabled: true // Enables/disables web performance metrics
+}
+```
+
+### 2. 🔗 Commerce URL
+```javascript
+commerceUrl: string // Backend API URL (taken from SERVICE_BACKEND_URL environment variable)
+```
+
+### 3. 🏷️ Product Attributes
+```javascript
+commonProductAttributes: [
+  {
+    translationKey: 'color', // Translation key
+    key: 'color'             // Attribute key from API
+  },
+  {
+    translationKey: 'size',
+    key: 'size'
+  }
+]
+```
+
+### 4. 🌍 Localization Settings
+```javascript
+localization: {
+  // Supported languages
+  locales: [
+    {
+      label: 'EN',           // Display label
+      value: 'en',           // Language code in ISO 639-1 format
+      localePath: 'en',      // URL path
+      apiValue: 'en-us',     // Value used for API
+      rtl: false             // Right-to-left writing (true for Arabic, Hebrew)
+    }
+  ],
+  
+  // Supported currencies
+  currencies: [
+    {
+      label: 'USD',          // Display label
+      code: 'usd',           // Currency code in ISO 4217 format
+      decimalScale: 2        // Number of decimal places (optional)
+    }
+  ],
+  
+  defaultLocaleValue: 'en',  // Default language
+  localeUrlStrategy: LocaleUrlStrategy.HideDefaultLocale, // URL strategy
+  redirectToDefaultLocale: true, // Redirect to default locale
+  defaultCurrencyCode: 'usd', // Default currency
+  
+  // Dynamic currency determination (optional)
+  getActiveCurrencyCode: ({ req, locale, defaultCurrencyCode }) => {
+    // Custom currency determination logic
+    return defaultCurrencyCode;
+  },
+  
+  // Locale included pretty URL pattern (optional)
+  localeIncludedPrettyUrlPattern: new RegExp('.+/pages/.+$')
+}
+```
+
+#### Locale URL Strategies:
+- `LocaleUrlStrategy.HideDefaultLocale`: Default language is hidden in URL
+- `LocaleUrlStrategy.ShowAllLocales`: All languages are shown in URL
+- `LocaleUrlStrategy.HideAllLocales`: No language is shown in URL
+
+### 5. 🔄 URL Rewrites
+```javascript
+rewrites: [
+  {
+    source: '/auth',         // Source URL
+    destination: '/auth'     // Destination URL
+  }
+]
+```
+
+### 6. ⚡ Redis Cache Settings
+```javascript
+redis: {
+  defaultExpirationTime: 900 // Default cache duration (seconds)
+}
+```
+
+### 7. 💳 Checkout Settings
+```javascript
+checkout: {
+  // Payment options to exclude from iframe (deprecated)
+  iframeExcludedPaymentOptions: ['payment-option-slug'],
+  
+  // Payment options to include in iframe
+  iframeIncludedPaymentOptions: ['payment-option-slug'],
+  
+  // Additional payment types
+  extraPaymentTypes: ['custom-payment-type'],
+  
+  // Masterpass JS URL
+  masterpassJsUrl: 'https://example.com/masterpass.js'
+}
+```
+
+### 8. ⚙️ Other Settings
+```javascript
+// Enable custom 404 page
+customNotFoundEnabled: false,
+
+// Use optimized translations
+useOptimizedTranslations: true,
+
+// Use pretty URL route
+usePrettyUrlRoute: true,
+
+// Plugin settings
+plugins: {
+  'plugin-name': {
+    setting1: 'value1',
+    setting2: 'value2'
+  }
+},
+
+// Proxy headers - determines which headers should be passed to Commerce API
+includedProxyHeaders: ['x-custom-header', 'x-forwarded-for', 'user-agent'],
+
+// Commerce redirection ignore list
+commerceRedirectionIgnoreList: ['/api/', '/_next/'],
+
+// Reset basket when currency changes
+resetBasketOnCurrencyChange: true,
+
+// Frontend IDs used to pass x-frontend-id header to commerce
+frontendIds: {
+  'frontend-name': 123
+}
+```
+
+## Detailed Explanations
+
+### 🔒 includedProxyHeaders
+
+This setting determines which HTTP headers should be passed in proxy requests from the Next.js application to the Commerce API.
+
+#### How It Works?
+
+1. **Default Behavior**: The system does not pass certain headers to the Commerce API by default
+2. **Override Mechanism**: Headers specified in the `includedProxyHeaders` array are passed to the Commerce API even if they are in the excluded list
+
+#### Why Is It Used?
+
+- **🔐 Security**: Prevents headers containing sensitive information from being passed to the Commerce API
+- **⚡ Performance**: Prevents unnecessary headers from being passed
+- **🔧 Flexibility**: Allows specific headers to be passed for special cases
+
+#### Usage Example
+
+```javascript
+includedProxyHeaders: [
+  'x-forwarded-for',
+  'user-agent', 
+  'x-custom-header',
+  'x-device-type'
+]
+```
+
+### 🚫 commerceRedirectionIgnoreList
+
+This setting determines which URL patterns should disable redirections (redirects) coming from the Commerce API.
+
+#### How It Works?
+
+1. **Middleware Process**: The `url-redirection.ts` middleware runs on every URL request
+2. **Commerce Check**: The middleware sends the current URL to the Commerce API
+3. **Redirect Check**: If a redirect response comes from the Commerce API, `commerceRedirectionIgnoreList` is checked
+4. **Pattern Matching**: If the redirect URL matches one of the patterns in the ignore list, the redirect is not performed
+
+#### Why Is It Used?
+
+- Ensures that certain pages are not affected by Commerce redirects
+
+#### Usage Example
+
+```javascript
+commerceRedirectionIgnoreList: ['/users/reset']
+```
+
+## Example Configuration
+
+```javascript
+const { LocaleUrlStrategy } = require('@akinon/next/localization');
+const { ROUTES } = require('@theme/routes');
+
+const commerceUrl = encodeURI(process.env.SERVICE_BACKEND_URL ?? 'default');
+
+/** @type {import('@akinon/next/types').Settings} */
+module.exports = {
+  webVitals: {
+    enabled: true
+  },
+  commerceUrl,
+  commonProductAttributes: [
+    { translationKey: 'color', key: 'color' },
+    { translationKey: 'size', key: 'size' }
+  ],
+  localization: {
+    locales: [
+      {
+        label: 'EN',
+        value: 'en',
+        localePath: 'en',
+        apiValue: 'en-us',
+        rtl: false
+      },
+      {
+        label: 'TR',
+        value: 'tr',
+        localePath: 'tr',
+        apiValue: 'tr-tr',
+        rtl: false
+      }
+    ],
+    currencies: [
+      {
+        label: 'USD',
+        code: 'usd',
+        decimalScale: 2
+      },
+      {
+        label: 'TRY',
+        code: 'try',
+        decimalScale: 2
+      }
+    ],
+    defaultLocaleValue: 'en',
+    localeUrlStrategy: LocaleUrlStrategy.HideDefaultLocale,
+    redirectToDefaultLocale: true,
+    defaultCurrencyCode: 'usd'
+  },
+  rewrites: [
+    {
+      source: ROUTES.AUTH,
+      destination: '/auth'
+    }
+  ],
+  redis: {
+    defaultExpirationTime: 900
+  },
+  customNotFoundEnabled: false
+};
+```
+
+## Plugin Configuration
+
+The `plugins` setting allows you to customize the behavior of plugins in the ProjectZero ecosystem.
+
+### 🎛️ How It Works?
+
+1. **Plugin System**: Plugins are loaded through the `PluginModule` component
+2. **Settings Integration**: Each plugin gets its own settings through `settings.plugins[pluginName]`
+3. **Dynamic Loading**: Plugins are loaded only when needed (lazy loading)
+4. **Customization**: Each plugin has its own specific settings
+
+### 🚀 Example: pz-akifast Plugin Configuration
+
+```javascript
+plugins: {
+  'pz-akifast': {
+    quickLogin: false,  // Hide quick login button
+    pdp: false,         // Hide checkout button on product detail page
+    basket: true        // Show checkout button on basket page
+  }
+}
+```
+
+
+### 💡 Plugin Usage Examples
+
+#### Akifast Quick Login Button
+```javascript
+// settings.js
+plugins: {
+  'pz-akifast': {
+    quickLogin: true  // Show button
+  }
+}
+```
+
+#### Akifast Checkout Button
+```javascript
+// settings.js
+plugins: {
+  'pz-akifast': {
+    pdp: true,    // Show on product detail page
+    basket: false // Hide on basket page
+  }
+}
+```
+
+### ⚠️ Things to Consider
+
+1. **Plugin Names**: Plugin names must match exactly (e.g., `pz-akifast`)
+5. **Performance**: Plugins are loaded only when needed
+
+## Important Notes
+
+1. **📝 TypeScript Support**: The file provides TypeScript support with `@type` comment
+2. **🌐 Environment Variables**: Commerce URL is taken from `SERVICE_BACKEND_URL` environment variable
+3. **📦 Imports**: Required modules must be imported at the beginning of the file
+4. **✅ Validation**: All settings must comply with the Settings interface
+5. **⚡ Performance**: Redis cache settings affect performance
+6. **🌍 Localization**: Language and currency settings directly affect the e-commerce experience
+7. **🔒 Proxy Headers**: The `includedProxyHeaders` setting is critical for security and performance
+8. **🚫 Redirect Control**: The `commerceRedirectionIgnoreList` setting is important for protecting APIs and static files

package/app-template/AGENTS.md

@@ -0,0 +1,7 @@
+# Project Zero Next.js - Developer Instructions
+
+## 📚 Available Instruction Files
+
+This project contains comprehensive instruction files to guide developers through different aspects of the Project Zero Next.js e-commerce platform.
+
+**[.github/instructions/](.github/instructions/)**

package/app-template/CHANGELOG.md

@@ -1,5 +1,33 @@
 # projectzeronext
 
+## 1.96.0
+
+### Minor Changes
+
+- 994dafe: ZERO-3616: Add settings instruction file
+- 48bf7bd: ZERO-3612: Add checkout instruction
+
+### Patch Changes
+
+- Updated dependencies [af5c93a]
+- Updated dependencies [a420947]
+  - @akinon/next@1.96.0
+  - @akinon/pz-akifast@1.96.0
+  - @akinon/pz-b2b@1.96.0
+  - @akinon/pz-basket-gift-pack@1.96.0
+  - @akinon/pz-bkm@1.96.0
+  - @akinon/pz-checkout-gift-pack@1.96.0
+  - @akinon/pz-click-collect@1.96.0
+  - @akinon/pz-credit-payment@1.96.0
+  - @akinon/pz-gpay@1.96.0
+  - @akinon/pz-masterpass@1.96.0
+  - @akinon/pz-one-click-checkout@1.96.0
+  - @akinon/pz-otp@1.96.0
+  - @akinon/pz-pay-on-delivery@1.96.0
+  - @akinon/pz-saved-card@1.96.0
+  - @akinon/pz-tabby-extension@1.96.0
+  - @akinon/pz-tamara-extension@1.96.0
+
 ## 1.95.0
 
 ### Patch Changes

package/app-template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectzeronext",
-  "version": "1.95.0",
+  "version": "1.96.0",
   "private": true,
   "license": "MIT",
   "scripts": {
@@ -24,22 +24,22 @@
     "test:middleware": "jest middleware-matcher.test.ts --bail"
   },
   "dependencies": {
-    "@akinon/next": "1.95.0",
-    "@akinon/pz-akifast": "1.95.0",
-    "@akinon/pz-b2b": "1.95.0",
-    "@akinon/pz-basket-gift-pack": "1.95.0",
-    "@akinon/pz-bkm": "1.95.0",
-    "@akinon/pz-checkout-gift-pack": "1.95.0",
-    "@akinon/pz-click-collect": "1.95.0",
-    "@akinon/pz-credit-payment": "1.95.0",
-    "@akinon/pz-gpay": "1.95.0",
-    "@akinon/pz-masterpass": "1.95.0",
-    "@akinon/pz-one-click-checkout": "1.95.0",
-    "@akinon/pz-otp": "1.95.0",
-    "@akinon/pz-pay-on-delivery": "1.95.0",
-    "@akinon/pz-saved-card": "1.95.0",
-    "@akinon/pz-tabby-extension": "1.95.0",
-    "@akinon/pz-tamara-extension": "1.95.0",
+    "@akinon/next": "1.96.0",
+    "@akinon/pz-akifast": "1.96.0",
+    "@akinon/pz-b2b": "1.96.0",
+    "@akinon/pz-basket-gift-pack": "1.96.0",
+    "@akinon/pz-bkm": "1.96.0",
+    "@akinon/pz-checkout-gift-pack": "1.96.0",
+    "@akinon/pz-click-collect": "1.96.0",
+    "@akinon/pz-credit-payment": "1.96.0",
+    "@akinon/pz-gpay": "1.96.0",
+    "@akinon/pz-masterpass": "1.96.0",
+    "@akinon/pz-one-click-checkout": "1.96.0",
+    "@akinon/pz-otp": "1.96.0",
+    "@akinon/pz-pay-on-delivery": "1.96.0",
+    "@akinon/pz-saved-card": "1.96.0",
+    "@akinon/pz-tabby-extension": "1.96.0",
+    "@akinon/pz-tamara-extension": "1.96.0",
     "@hookform/resolvers": "2.9.0",
     "@next/third-parties": "14.1.0",
     "@react-google-maps/api": "2.17.1",
@@ -62,7 +62,7 @@
     "yup": "0.32.11"
   },
   "devDependencies": {
-    "@akinon/eslint-plugin-projectzero": "1.95.0",
+    "@akinon/eslint-plugin-projectzero": "1.96.0",
     "@semantic-release/changelog": "6.0.2",
     "@semantic-release/exec": "6.0.3",
     "@semantic-release/git": "10.0.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akinon/projectzero",
-  "version": "1.96.0-snapshot-ZERO-35861-20250908151109",
+  "version": "1.96.0",
   "private": false,
   "description": "CLI tool to manage your Project Zero Next project",
   "bin": {