@doswiftly/cli 0.1.1

package/templates/storefront-nextjs-shadcn/hooks/use-filter-params.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Tests for useFilterParams hook
+ *
+ * Requirements: R35.20, R35.21, R35.22
+ */
+
+// Note: This is a test specification file. In a real test setup, you would use
+// @testing-library/react-hooks and mock next/navigation.
+
+import type { AppliedFilters } from "@/components/filters/dynamic-attribute-filters";
+
+/**
+ * URL Parameter Parsing Tests (R35.20)
+ */
+describe("URL Parameter Parsing", () => {
+  describe("parseSearchParams", () => {
+    it("should parse discrete attribute filters from URL", () => {
+      // URL: ?attr_color=red,blue
+      const params = new URLSearchParams("attr_color=red,blue");
+      const expected: Partial<AppliedFilters> = {
+        attributes: { color: ["red", "blue"] },
+      };
+      // Implementation would parse this
+    });
+
+    it("should parse multiple attribute filters", () => {
+      // URL: ?attr_color=red&attr_size=xl,xxl
+      const params = new URLSearchParams("attr_color=red&attr_size=xl,xxl");
+      const expected: Partial<AppliedFilters> = {
+        attributes: {
+          color: ["red"],
+          size: ["xl", "xxl"],
+        },
+      };
+    });
+
+    it("should parse range attribute filters", () => {
+      // URL: ?attr_weight_min=100&attr_weight_max=500
+      const params = new URLSearchParams("attr_weight_min=100&attr_weight_max=500");
+      const expected: Partial<AppliedFilters> = {
+        ranges: { weight: { min: 100, max: 500 } },
+      };
+    });
+
+    it("should parse price filters", () => {
+      // URL: ?min_price=50&max_price=200
+      const params = new URLSearchParams("min_price=50&max_price=200");
+      const expected: Partial<AppliedFilters> = {
+        price: { min: 50, max: 200 },
+      };
+    });
+
+    it("should parse category filter", () => {
+      // URL: ?category=category-id
+      const params = new URLSearchParams("category=category-id");
+      const expected: Partial<AppliedFilters> = {
+        categoryId: "category-id",
+      };
+    });
+
+    it("should handle empty values", () => {
+      // URL: ?attr_color=
+      const params = new URLSearchParams("attr_color=");
+      const expected: Partial<AppliedFilters> = {
+        attributes: {},
+      };
+    });
+  });
+});
+
+/**
+ * URL Serialization Tests (R35.21)
+ */
+describe("URL Serialization", () => {
+  describe("serializeToSearchParams", () => {
+    it("should serialize discrete attribute filters", () => {
+      const filters: AppliedFilters = {
+        attributes: { color: ["red", "blue"] },
+        ranges: {},
+      };
+      // Expected URL: ?attr_color=red,blue
+    });
+
+    it("should serialize range attribute filters", () => {
+      const filters: AppliedFilters = {
+        attributes: {},
+        ranges: { weight: { min: 100, max: 500 } },
+      };
+      // Expected URL: ?attr_weight_min=100&attr_weight_max=500
+    });
+
+    it("should serialize price filters", () => {
+      const filters: AppliedFilters = {
+        attributes: {},
+        ranges: {},
+        price: { min: 50, max: 200 },
+      };
+      // Expected URL: ?min_price=50&max_price=200
+    });
+
+    it("should preserve non-filter params", () => {
+      const filters: AppliedFilters = {
+        attributes: { color: ["red"] },
+        ranges: {},
+      };
+      const existingParams = new URLSearchParams("page=2&sort=price");
+      // Expected URL: ?page=2&sort=price&attr_color=red
+    });
+
+    it("should omit empty filters", () => {
+      const filters: AppliedFilters = {
+        attributes: { color: [] },
+        ranges: { weight: {} },
+      };
+      // Expected URL: (empty or just non-filter params)
+    });
+  });
+});
+
+/**
+ * Clear Filters Tests (R35.22)
+ */
+describe("Clear Filters", () => {
+  it("should clear single attribute filter", () => {
+    const initial: AppliedFilters = {
+      attributes: { color: ["red"], size: ["xl"] },
+      ranges: {},
+    };
+    // After clearing color:
+    const expected: AppliedFilters = {
+      attributes: { size: ["xl"] },
+      ranges: {},
+    };
+  });
+
+  it("should clear all filters", () => {
+    const initial: AppliedFilters = {
+      attributes: { color: ["red"], size: ["xl"] },
+      ranges: { weight: { min: 100, max: 500 } },
+      price: { min: 50, max: 200 },
+      categoryId: "category-1",
+    };
+    const expected: AppliedFilters = {
+      attributes: {},
+      ranges: {},
+      price: undefined,
+      categoryId: undefined,
+    };
+  });
+
+  it("should maintain non-attribute params when clearing", () => {
+    // URL: ?page=2&sort=price&attr_color=red
+    // After clearAllFilters:
+    // URL: ?page=2&sort=price
+  });
+});
+
+/**
+ * Debounce Tests
+ */
+describe("Debounce", () => {
+  it("should debounce URL updates", () => {
+    // Multiple rapid filter changes should result in single URL update
+    // after debounce delay (300ms default)
+  });
+
+  it("should use custom debounce delay if provided", () => {
+    // With debounceMs: 500, updates should wait 500ms
+  });
+});
+
+// Export for test runner
+export {};

package/templates/storefront-nextjs-shadcn/hooks/use-filter-params.ts

@@ -0,0 +1,298 @@
+"use client";
+
+import { useCallback, useMemo, useRef, useEffect } from "react";
+import { useSearchParams, useRouter, usePathname } from "next/navigation";
+import type { AppliedFilters } from "@/components/filters/dynamic-attribute-filters";
+
+/**
+ * useFilterParams - Hook for syncing filter state with URL
+ *
+ * URL parameter format:
+ * - Discrete attributes: ?attr_color=red,blue&attr_size=xl
+ * - Range attributes: ?attr_price_min=100&attr_price_max=500
+ * - Price filter: ?min_price=50&max_price=200
+ * - Category: ?category=category-id
+ *
+ * Features:
+ * - Debounced URL updates (300ms)
+ * - Multi-value support (comma-separated)
+ * - Range value support (min/max pairs)
+ * - SSR-safe (uses useSearchParams)
+ *
+ * Requirements: R35.20, R35.21, R35.22
+ */
+
+const ATTR_PREFIX = "attr_";
+const RANGE_MIN_SUFFIX = "_min";
+const RANGE_MAX_SUFFIX = "_max";
+const DEBOUNCE_MS = 300;
+
+export interface UseFilterParamsOptions {
+  /** Debounce delay in ms (default: 300) */
+  debounceMs?: number;
+}
+
+export interface UseFilterParamsReturn {
+  /** Current applied filters parsed from URL */
+  appliedFilters: AppliedFilters;
+  /** Update attribute filter values */
+  setAttributeFilter: (attributeId: string, values: string[]) => void;
+  /** Update range filter values */
+  setRangeFilter: (attributeId: string, range: { min?: number; max?: number }) => void;
+  /** Update price filter */
+  setPriceFilter: (range: { min?: number; max?: number }) => void;
+  /** Update category filter */
+  setCategoryFilter: (categoryId?: string) => void;
+  /** Clear all filters */
+  clearAllFilters: () => void;
+  /** Get URL for sharing/linking with current filters */
+  getFilteredUrl: () => string;
+}
+
+/**
+ * Parse URL search params into AppliedFilters object
+ */
+function parseSearchParams(searchParams: URLSearchParams): AppliedFilters {
+  const attributes: Record<string, string[]> = {};
+  const ranges: Record<string, { min?: number; max?: number }> = {};
+  let price: { min?: number; max?: number } | undefined;
+  let categoryId: string | undefined;
+
+  // Parse category
+  const categoryParam = searchParams.get("category");
+  if (categoryParam) {
+    categoryId = categoryParam;
+  }
+
+  // Parse price
+  const minPrice = searchParams.get("min_price");
+  const maxPrice = searchParams.get("max_price");
+  if (minPrice || maxPrice) {
+    price = {
+      min: minPrice ? parseFloat(minPrice) : undefined,
+      max: maxPrice ? parseFloat(maxPrice) : undefined,
+    };
+  }
+
+  // Parse attribute filters
+  for (const [key, value] of searchParams.entries()) {
+    if (key.startsWith(ATTR_PREFIX)) {
+      const attrKey = key.slice(ATTR_PREFIX.length);
+
+      // Check if it's a range parameter (ends with _min or _max)
+      if (attrKey.endsWith(RANGE_MIN_SUFFIX)) {
+        const attrId = attrKey.slice(0, -RANGE_MIN_SUFFIX.length);
+        const numValue = parseFloat(value);
+        if (!isNaN(numValue)) {
+          if (!ranges[attrId]) ranges[attrId] = {};
+          ranges[attrId].min = numValue;
+        }
+      } else if (attrKey.endsWith(RANGE_MAX_SUFFIX)) {
+        const attrId = attrKey.slice(0, -RANGE_MAX_SUFFIX.length);
+        const numValue = parseFloat(value);
+        if (!isNaN(numValue)) {
+          if (!ranges[attrId]) ranges[attrId] = {};
+          ranges[attrId].max = numValue;
+        }
+      } else {
+        // Discrete attribute values (comma-separated)
+        const values = value.split(",").filter(Boolean);
+        if (values.length > 0) {
+          attributes[attrKey] = values;
+        }
+      }
+    }
+  }
+
+  return { attributes, ranges, price, categoryId };
+}
+
+/**
+ * Serialize AppliedFilters to URLSearchParams
+ */
+function serializeToSearchParams(
+  filters: AppliedFilters,
+  existingParams?: URLSearchParams
+): URLSearchParams {
+  const params = new URLSearchParams();
+
+  // Preserve non-filter params (like page, sort)
+  if (existingParams) {
+    for (const [key, value] of existingParams.entries()) {
+      if (
+        !key.startsWith(ATTR_PREFIX) &&
+        key !== "min_price" &&
+        key !== "max_price" &&
+        key !== "category"
+      ) {
+        params.set(key, value);
+      }
+    }
+  }
+
+  // Category
+  if (filters.categoryId) {
+    params.set("category", filters.categoryId);
+  }
+
+  // Price
+  if (filters.price?.min !== undefined) {
+    params.set("min_price", filters.price.min.toString());
+  }
+  if (filters.price?.max !== undefined) {
+    params.set("max_price", filters.price.max.toString());
+  }
+
+  // Discrete attributes
+  for (const [attrId, values] of Object.entries(filters.attributes)) {
+    if (values.length > 0) {
+      params.set(`${ATTR_PREFIX}${attrId}`, values.join(","));
+    }
+  }
+
+  // Range attributes
+  for (const [attrId, range] of Object.entries(filters.ranges)) {
+    if (range.min !== undefined) {
+      params.set(`${ATTR_PREFIX}${attrId}${RANGE_MIN_SUFFIX}`, range.min.toString());
+    }
+    if (range.max !== undefined) {
+      params.set(`${ATTR_PREFIX}${attrId}${RANGE_MAX_SUFFIX}`, range.max.toString());
+    }
+  }
+
+  return params;
+}
+
+export function useFilterParams(
+  options: UseFilterParamsOptions = {}
+): UseFilterParamsReturn {
+  const { debounceMs = DEBOUNCE_MS } = options;
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  // Debounce timer ref
+  const debounceRef = useRef<NodeJS.Timeout | null>(null);
+
+  // Parse current filters from URL
+  const appliedFilters = useMemo(() => {
+    return parseSearchParams(searchParams);
+  }, [searchParams]);
+
+  // Update URL with debouncing
+  const updateUrl = useCallback(
+    (newFilters: AppliedFilters) => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+
+      debounceRef.current = setTimeout(() => {
+        const params = serializeToSearchParams(newFilters, searchParams);
+        const queryString = params.toString();
+        const newUrl = queryString ? `${pathname}?${queryString}` : pathname;
+        router.push(newUrl, { scroll: false });
+      }, debounceMs);
+    },
+    [pathname, searchParams, router, debounceMs]
+  );
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, []);
+
+  // Set attribute filter values
+  const setAttributeFilter = useCallback(
+    (attributeId: string, values: string[]) => {
+      const newFilters = { ...appliedFilters };
+      newFilters.attributes = { ...newFilters.attributes };
+
+      if (values.length > 0) {
+        newFilters.attributes[attributeId] = values;
+      } else {
+        delete newFilters.attributes[attributeId];
+      }
+
+      updateUrl(newFilters);
+    },
+    [appliedFilters, updateUrl]
+  );
+
+  // Set range filter values
+  const setRangeFilter = useCallback(
+    (attributeId: string, range: { min?: number; max?: number }) => {
+      const newFilters = { ...appliedFilters };
+      newFilters.ranges = { ...newFilters.ranges };
+
+      if (range.min !== undefined || range.max !== undefined) {
+        newFilters.ranges[attributeId] = range;
+      } else {
+        delete newFilters.ranges[attributeId];
+      }
+
+      updateUrl(newFilters);
+    },
+    [appliedFilters, updateUrl]
+  );
+
+  // Set price filter
+  const setPriceFilter = useCallback(
+    (range: { min?: number; max?: number }) => {
+      const newFilters = { ...appliedFilters };
+
+      if (range.min !== undefined || range.max !== undefined) {
+        newFilters.price = range;
+      } else {
+        newFilters.price = undefined;
+      }
+
+      updateUrl(newFilters);
+    },
+    [appliedFilters, updateUrl]
+  );
+
+  // Set category filter
+  const setCategoryFilter = useCallback(
+    (categoryId?: string) => {
+      const newFilters = { ...appliedFilters };
+      newFilters.categoryId = categoryId;
+      updateUrl(newFilters);
+    },
+    [appliedFilters, updateUrl]
+  );
+
+  // Clear all filters
+  const clearAllFilters = useCallback(() => {
+    const newFilters: AppliedFilters = {
+      attributes: {},
+      ranges: {},
+      price: undefined,
+      categoryId: undefined,
+    };
+    updateUrl(newFilters);
+  }, [updateUrl]);
+
+  // Get URL for sharing
+  const getFilteredUrl = useCallback(() => {
+    const params = serializeToSearchParams(appliedFilters, searchParams);
+    const queryString = params.toString();
+    const baseUrl = typeof window !== "undefined" ? window.location.origin : "";
+    return queryString ? `${baseUrl}${pathname}?${queryString}` : `${baseUrl}${pathname}`;
+  }, [appliedFilters, pathname, searchParams]);
+
+  return {
+    appliedFilters,
+    setAttributeFilter,
+    setRangeFilter,
+    setPriceFilter,
+    setCategoryFilter,
+    clearAllFilters,
+    getFilteredUrl,
+  };
+}
+
+export default useFilterParams;

package/templates/storefront-nextjs-shadcn/lib/auth/cookies.ts

@@ -0,0 +1,220 @@
+/**
+ * Cookie Helpers for Authentication
+ *
+ * Provides utilities for managing authentication cookies in both
+ * client-side and server-side contexts.
+ *
+ * Security Notes:
+ * - Cookies are httpOnly (set via API routes, not client-side)
+ * - Cookies are secure in production (HTTPS only)
+ * - Cookies are SameSite=Lax to prevent CSRF
+ * - Token validation happens on GraphQL backend
+ *
+ * @see lib/auth/routes.ts - Cookie name constant
+ * @see app/api/auth/set-token/route.ts - Server-side cookie setter
+ * @see app/api/auth/clear-token/route.ts - Server-side cookie clearer
+ */
+
+import { AUTH_COOKIE_NAME } from "./routes";
+
+/**
+ * Cookie configuration for authentication token
+ */
+export const AUTH_COOKIE_CONFIG = {
+  name: AUTH_COOKIE_NAME,
+  maxAge: 60 * 60 * 24 * 30, // 30 days (in seconds)
+  path: "/",
+  sameSite: "lax" as const,
+  secure: process.env.NODE_ENV === "production",
+  httpOnly: true, // Cannot be accessed via JavaScript (security)
+} as const;
+
+/**
+ * Get authentication token from cookies (client-side)
+ *
+ * Note: This only works if the cookie is NOT httpOnly.
+ * For httpOnly cookies, use server-side methods or API routes.
+ *
+ * @returns Token string or null if not found
+ *
+ * @example
+ * ```tsx
+ * const token = getAuthToken();
+ * if (token) {
+ *   // User is authenticated
+ * }
+ * ```
+ */
+export function getAuthToken(): string | null {
+  if (typeof window === "undefined") {
+    return null; // Server-side
+  }
+
+  const cookies = document.cookie.split("; ");
+  const authCookie = cookies.find((c) => c.startsWith(`${AUTH_COOKIE_NAME}=`));
+
+  if (!authCookie) {
+    return null;
+  }
+
+  return authCookie.split("=")[1] || null;
+}
+
+/**
+ * Check if user is authenticated (client-side)
+ *
+ * Note: This checks cookie EXISTENCE, not VALIDITY.
+ * Token validation happens on the GraphQL backend.
+ *
+ * @returns True if auth cookie exists
+ *
+ * @example
+ * ```tsx
+ * const isAuthenticated = isAuthTokenPresent();
+ * if (isAuthenticated) {
+ *   // Show authenticated UI
+ * }
+ * ```
+ */
+export function isAuthTokenPresent(): boolean {
+  return getAuthToken() !== null;
+}
+
+/**
+ * Set authentication token (via API route)
+ *
+ * This function calls the API route to set an httpOnly cookie.
+ * Direct client-side cookie setting is NOT secure for auth tokens.
+ *
+ * @param token - Customer access token from GraphQL
+ * @returns Promise that resolves when cookie is set
+ *
+ * @example
+ * ```tsx
+ * const { customerAccessToken } = await loginMutation.mutateAsync({
+ *   input: { email, password }
+ * });
+ *
+ * if (customerAccessToken) {
+ *   await setAuthToken(customerAccessToken.accessToken);
+ * }
+ * ```
+ */
+export async function setAuthToken(token: string): Promise<void> {
+  const response = await fetch("/api/auth/set-token", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ token }),
+  });
+
+  if (!response.ok) {
+    throw new Error("Failed to set authentication token");
+  }
+}
+
+/**
+ * Clear authentication token (via API route)
+ *
+ * This function calls the API route to clear the httpOnly cookie.
+ *
+ * @returns Promise that resolves when cookie is cleared
+ *
+ * @example
+ * ```tsx
+ * await clearAuthToken();
+ * router.push('/auth/login');
+ * ```
+ */
+export async function clearAuthToken(): Promise<void> {
+  const response = await fetch("/api/auth/clear-token", {
+    method: "POST",
+  });
+
+  if (!response.ok) {
+    throw new Error("Failed to clear authentication token");
+  }
+}
+
+/**
+ * Parse cookie string into key-value object
+ *
+ * Utility function for parsing cookie strings in server-side contexts.
+ *
+ * @param cookieString - Raw cookie string from request headers
+ * @returns Object with cookie key-value pairs
+ *
+ * @example
+ * ```tsx
+ * const cookies = parseCookies(request.headers.get('cookie') || '');
+ * const token = cookies[AUTH_COOKIE_NAME];
+ * ```
+ */
+export function parseCookies(cookieString: string): Record<string, string> {
+  return cookieString
+    .split("; ")
+    .reduce((acc, cookie) => {
+      const [key, value] = cookie.split("=");
+      if (key && value) {
+        acc[key] = value;
+      }
+      return acc;
+    }, {} as Record<string, string>);
+}
+
+/**
+ * Serialize cookie for Set-Cookie header
+ *
+ * Utility function for creating Set-Cookie header values in API routes.
+ *
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie options (maxAge, path, etc.)
+ * @returns Serialized cookie string for Set-Cookie header
+ *
+ * @example
+ * ```tsx
+ * const cookieHeader = serializeCookie(
+ *   AUTH_COOKIE_NAME,
+ *   token,
+ *   AUTH_COOKIE_CONFIG
+ * );
+ * response.headers.set('Set-Cookie', cookieHeader);
+ * ```
+ */
+export function serializeCookie(
+  name: string,
+  value: string,
+  options: {
+    maxAge?: number;
+    path?: string;
+    sameSite?: "strict" | "lax" | "none";
+    secure?: boolean;
+    httpOnly?: boolean;
+  } = {}
+): string {
+  const parts = [`${name}=${value}`];
+
+  if (options.maxAge) {
+    parts.push(`Max-Age=${options.maxAge}`);
+  }
+
+  if (options.path) {
+    parts.push(`Path=${options.path}`);
+  }
+
+  if (options.sameSite) {
+    parts.push(`SameSite=${options.sameSite}`);
+  }
+
+  if (options.secure) {
+    parts.push("Secure");
+  }
+
+  if (options.httpOnly) {
+    parts.push("HttpOnly");
+  }
+
+  return parts.join("; ");
+}