@usequeek/theme-kit 0.1.0

package/hooks/use-auth-flow.tsx

@@ -0,0 +1,346 @@
+'use client';
+
+import { createContext, useContext, useState, type ReactNode } from 'react';
+import { QueekSdkError, type EmailVerifyOtpResponse } from '@queekai/client-sdk';
+import { useStorefront } from '../provider';
+import { getQueekClient, setAuthTokens, QUEEK_AUTH_URL } from '../sdk/queek-client';
+import { useAuthModalStore } from '../stores/auth-modal-store';
+import { useUserStore } from '../stores/user-store';
+
+export type AuthStep =
+  | 'email-otp'
+  | 'email-otp-verify'
+  | 'signup'
+  | 'email-login'
+  | 'email-register';
+
+export interface AuthFlowState {
+  step: AuthStep;
+  otp: string;
+  firstName: string;
+  lastName: string;
+  email: string;
+  password: string;
+  loading: boolean;
+  error: string | null;
+}
+
+export interface AuthFlowActions {
+  setOtp: (value: string) => void;
+  setFirstName: (value: string) => void;
+  setLastName: (value: string) => void;
+  setEmail: (value: string) => void;
+  setPassword: (value: string) => void;
+  submitEmailRequestOtp: () => Promise<void>;
+  submitEmailVerifyOtp: () => Promise<void>;
+  submitRegister: () => Promise<void>;
+  submitEmailLogin: () => Promise<void>;
+  submitEmailRegister: () => Promise<void>;
+  initiateGoogleAuth: () => Promise<void>;
+  reset: () => void;
+  goToEmailOtp: () => void;
+  goToEmailLogin: () => void;
+  goToEmailRegister: () => void;
+}
+
+export type AuthFlowValue = AuthFlowState & AuthFlowActions;
+
+const EMAIL_OTP_LENGTH = 6;
+
+interface PasswordAuthData {
+  access_token: string;
+  refresh_token: string;
+  user: {
+    id: string;
+    name: string;
+    first_name?: string | null;
+    last_name?: string | null;
+    email: string | null;
+    phone?: string | null;
+    avatar: string | null;
+    profile_complete?: boolean;
+  };
+}
+
+function mapEmailError(err: unknown): string {
+  if (err instanceof QueekSdkError) {
+    switch (err.code) {
+      case 'invalid_credentials':
+        return 'Wrong email or password. Please try again.';
+      case 'login_mode_mismatch':
+        return 'This account uses a different sign-in method (Google or phone).';
+      case 'account_already_exists':
+        return 'Email already registered. Please sign in instead.';
+      case 'phone_already_exists':
+        return 'Phone number already in use.';
+      case 'otp_resend_too_soon':
+        return 'Please wait before requesting another code.';
+      case 'invalid_otp':
+        return 'Incorrect code. Please try again.';
+      default:
+        return err.message || 'Something went wrong. Please try again.';
+    }
+  }
+  return 'Something went wrong. Please try again.';
+}
+
+const AuthFlowContext = createContext<AuthFlowValue | null>(null);
+
+export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Element {
+  const { vendor } = useStorefront();
+  const closeModal = useAuthModalStore((s) => s.close);
+  const setUser = useUserStore((s) => s.setUser);
+
+  const [step, setStep] = useState<AuthStep>('email-otp');
+  const [otp, setOtp] = useState('');
+  const [verifiedToken, setVerifiedToken] = useState(''); // email OTP flow: server-issued token
+  const [firstName, setFirstName] = useState('');
+  const [lastName, setLastName] = useState('');
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  function applyUser(u: { id: string; name: string; first_name?: string | null; last_name?: string | null; email: string | null; phone?: string | null; avatar: string | null; profile_complete?: boolean }): void {
+    setUser({
+      id: u.id,
+      name: u.name,
+      first_name: u.first_name ?? '',
+      last_name: u.last_name ?? '',
+      email: u.email,
+      phone: u.phone ?? '',
+      avatar: u.avatar,
+      profile_complete: u.profile_complete ?? Boolean(u.phone),
+    });
+  }
+
+  // OAuth round-trip handling lives in core-modal-layer's GoogleCallbackHandler
+  // — it must stay mounted whether or not the auth modal is open.
+
+  // ── Email OTP flow (primary) ──────────────────────────────────────────────
+
+  const submitEmailRequestOtp = async (): Promise<void> => {
+    const trimmedEmail = email.trim();
+    if (!trimmedEmail) return;
+    setError(null);
+    setLoading(true);
+    try {
+      const client = getQueekClient(vendor.slug ?? undefined);
+      await client.auth.emailRequestOtp({ email: trimmedEmail });
+      setOtp('');
+      setStep('email-otp-verify');
+    } catch (err) {
+      setError(mapEmailError(err));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const submitEmailVerifyOtp = async (): Promise<void> => {
+    if (otp.length < EMAIL_OTP_LENGTH) return;
+    setError(null);
+    setLoading(true);
+    try {
+      const client = getQueekClient(vendor.slug ?? undefined);
+      const data: EmailVerifyOtpResponse = await client.auth.emailVerifyOtp({
+        email: email.trim(),
+        otpCode: otp,
+      });
+      if (data.needs_registration) {
+        setVerifiedToken(data.verified_token);
+        setStep('signup');
+        return;
+      }
+      // tokens already persisted by SDK
+      applyUser(data.user);
+      closeModal();
+    } catch (err) {
+      setError(mapEmailError(err));
+      setOtp('');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // ── Signup (email OTP flow) ───────────────────────────────────────────────
+
+  const submitRegister = async (): Promise<void> => {
+    if (!firstName.trim()) {
+      setError('Please enter your first name.');
+      return;
+    }
+    setError(null);
+    setLoading(true);
+    try {
+      const client = getQueekClient(vendor.slug ?? undefined);
+      const res = await client.auth.emailRegisterOtp({
+        firstName: firstName.trim(),
+        lastName: lastName.trim() || undefined,
+        verifiedToken,
+      });
+      // tokens already persisted by SDK
+      applyUser(res.user);
+      closeModal();
+    } catch (err) {
+      setError(err instanceof QueekSdkError ? err.message : 'Registration failed. Try again.');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // ── Email password flow ───────────────────────────────────────────────────
+
+  const submitEmailLogin = async (): Promise<void> => {
+    if (!email.trim() || !password) return;
+    setError(null);
+    setLoading(true);
+    try {
+      const client = getQueekClient(vendor.slug ?? undefined);
+      const res = await client.post<PasswordAuthData>('/client/auth/email/login', {
+        email: email.trim(),
+        password,
+        platform: 'client_web',
+      });
+      setAuthTokens(res.data.access_token, res.data.refresh_token);
+      applyUser(res.data.user);
+      closeModal();
+    } catch (err) {
+      setError(mapEmailError(err));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const submitEmailRegister = async (): Promise<void> => {
+    if (!firstName.trim() || !email.trim() || password.length < 8) return;
+    setError(null);
+    setLoading(true);
+    try {
+      const client = getQueekClient(vendor.slug ?? undefined);
+      const res = await client.post<PasswordAuthData>('/client/auth/email/register-password', {
+        first_name: firstName.trim(),
+        last_name: lastName.trim() || undefined,
+        email: email.trim(),
+        password,
+        phone: '',
+        platform: 'client_web',
+      });
+      setAuthTokens(res.data.access_token, res.data.refresh_token);
+      applyUser(res.data.user);
+      closeModal();
+    } catch (err) {
+      setError(mapEmailError(err));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // ── Google OAuth ──────────────────────────────────────────────────────────
+
+  const initiateGoogleAuth = async (): Promise<void> => {
+    setError(null);
+    setLoading(true);
+    try {
+      const returnTo = typeof window !== 'undefined' ? window.location.href : '';
+      const slug = vendor.slug ?? '';
+      const url = `${QUEEK_AUTH_URL}/oauth/google/start?channel=storefront&vendor_slug=${encodeURIComponent(slug)}&return_to=${encodeURIComponent(returnTo)}`;
+      // eslint-disable-next-line no-console
+      console.info('[google-auth] requesting redirect URL from', url);
+      const res = await fetch(url);
+      if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        // eslint-disable-next-line no-console
+        console.warn('[google-auth] redirect endpoint returned non-2xx', res.status, text);
+        throw new Error(`Failed to initiate Google auth (HTTP ${res.status}).`);
+      }
+      // Laravel envelope: { status, message, data: { url } }
+      const body = (await res.json()) as {
+        data?: { url?: string; redirect_url?: string };
+        url?: string;
+        redirect_url?: string;
+      };
+      const redirectUrl =
+        body.data?.url ?? body.data?.redirect_url ?? body.url ?? body.redirect_url;
+      if (redirectUrl) {
+        window.location.href = redirectUrl;
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn('[google-auth] no redirect URL in response body', body);
+        throw new Error('No redirect URL returned.');
+      }
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error('[google-auth] initiate failed', err);
+      setError('Could not connect to Google sign-in. Please try again.');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // ── Navigation ────────────────────────────────────────────────────────────
+
+  const reset = (): void => {
+    setStep('email-otp');
+    setOtp('');
+    setVerifiedToken('');
+    setFirstName('');
+    setLastName('');
+    setEmail('');
+    setPassword('');
+    setError(null);
+    setLoading(false);
+  };
+
+  const goToEmailOtp = (): void => {
+    setStep('email-otp');
+    setOtp('');
+    setVerifiedToken('');
+    setError(null);
+  };
+
+  const goToEmailLogin = (): void => {
+    setStep('email-login');
+    setError(null);
+  };
+
+  const goToEmailRegister = (): void => {
+    setStep('email-register');
+    setError(null);
+  };
+
+  const value: AuthFlowValue = {
+    step,
+    otp,
+    firstName,
+    lastName,
+    email,
+    password,
+    loading,
+    error,
+    setOtp,
+    setFirstName,
+    setLastName,
+    setEmail,
+    setPassword,
+    submitEmailRequestOtp,
+    submitEmailVerifyOtp,
+    submitRegister,
+    submitEmailLogin,
+    submitEmailRegister,
+    initiateGoogleAuth,
+    reset,
+    goToEmailOtp,
+    goToEmailLogin,
+    goToEmailRegister,
+  };
+
+  return <AuthFlowContext.Provider value={value}>{children}</AuthFlowContext.Provider>;
+}
+
+export function useAuthFlow(): AuthFlowValue {
+  const ctx = useContext(AuthFlowContext);
+  if (!ctx) {
+    throw new Error('useAuthFlow must be used within an AuthFlowProvider');
+  }
+  return ctx;
+}

package/hooks/use-auth.ts

@@ -0,0 +1,17 @@
+'use client';
+
+import { useAuthModalStore } from '../stores/auth-modal-store';
+import { useUserStore } from '../stores/user-store';
+
+export function useAuth() {
+  return {
+    user: useUserStore((state) => state.user),
+    isAuthenticated: useUserStore((state) => state.isAuthenticated),
+    setUser: useUserStore((state) => state.setUser),
+    logout: useUserStore((state) => state.logout),
+    openAuthModal: useAuthModalStore((state) => state.open),
+    closeAuthModal: useAuthModalStore((state) => state.close),
+    authModalOpen: useAuthModalStore((state) => state.isOpen),
+    authMode: useAuthModalStore((state) => state.mode),
+  };
+}

package/hooks/use-cart.ts

@@ -0,0 +1,14 @@
+'use client';
+
+import { useCartStore } from '../stores/cart-store';
+
+export function useCart() {
+  return {
+    items: useCartStore((state) => state.items),
+    addProduct: useCartStore((state) => state.addProduct),
+    addItemWithAddons: useCartStore((state) => state.addItemWithAddons),
+    setQuantity: useCartStore((state) => state.setQuantity),
+    removeItem: useCartStore((state) => state.removeItem),
+    clearShopCart: useCartStore((state) => state.clearShopCart),
+  };
+}

package/hooks/use-categories.ts

@@ -0,0 +1,112 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useStorefront } from '../provider';
+import { createBrowserClient } from '../sdk/client';
+
+export interface Category {
+  id: string;
+  slug: string;
+  name: string;
+  image?: string | null;
+  products_count?: number;
+  children?: Category[];
+}
+
+interface CategoriesResponse {
+  data: Category[];
+  message?: string;
+}
+
+/**
+ * Flatten a nested category tree into a single list so `ids` filters
+ * can resolve collections at any depth.
+ */
+function flattenCategories(items: Category[]): Category[] {
+  const out: Category[] = [];
+  const walk = (list: Category[]): void => {
+    for (const item of list) {
+      out.push(item);
+      if (Array.isArray(item.children) && item.children.length > 0) {
+        walk(item.children);
+      }
+    }
+  };
+  walk(items);
+  return out;
+}
+
+export function useCategories(options?: {
+  ids?: string[];
+  limit?: number;
+}): {
+  categories: Category[];
+  isLoading: boolean;
+} {
+  const { previewData, vendor } = useStorefront();
+  const [categories, setCategories] = useState<Category[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+
+  const idsKey = options?.ids?.join(',') ?? '';
+  const limit = options?.limit;
+
+  useEffect(() => {
+    let cancelled = false;
+    const previewCategories = previewData?.categories;
+    const client = createBrowserClient(vendor.slug ?? undefined);
+
+    async function run(): Promise<void> {
+      setIsLoading(true);
+
+      try {
+        if (Array.isArray(previewCategories)) {
+          let items = flattenCategories(previewCategories);
+
+          if (idsKey) {
+            const idSet = new Set(idsKey.split(','));
+            // Preserve input order for deterministic display.
+            const ordered = idsKey.split(',');
+            const byId = new Map(items.filter((c) => idSet.has(c.id)).map((c) => [c.id, c]));
+            items = ordered.map((id) => byId.get(id)).filter((c): c is Category => !!c);
+          }
+
+          if (!cancelled) {
+            setCategories(typeof limit === 'number' ? items.slice(0, limit) : items);
+            setIsLoading(false);
+          }
+          return;
+        }
+
+        const query: Record<string, string> = { include_empty: '1' };
+        const response = await client.get<CategoriesResponse>('/collections', query);
+        let items = flattenCategories(Array.isArray(response.data) ? response.data : []);
+
+        // Filter by specific IDs if provided — preserving input order
+        if (idsKey) {
+          const idSet = new Set(idsKey.split(','));
+          const ordered = idsKey.split(',');
+          const byId = new Map(items.filter((c) => idSet.has(c.id)).map((c) => [c.id, c]));
+          items = ordered.map((id) => byId.get(id)).filter((c): c is Category => !!c);
+        }
+
+        if (!cancelled) {
+          setCategories(typeof limit === 'number' ? items.slice(0, limit) : items);
+          setIsLoading(false);
+        }
+      } catch {
+        if (!cancelled) {
+          setCategories([]);
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void run();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [idsKey, limit, previewData?.categories, vendor.slug]);
+
+  return { categories, isLoading };
+}

package/hooks/use-collection-params.ts

@@ -0,0 +1,67 @@
+'use client';
+
+import { useCallback, useTransition } from 'react';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+import type { CollectionSort } from '../api/collections';
+
+const SORTS: CollectionSort[] = ['newest', 'popular', 'price_low', 'price_high'];
+
+export interface CollectionParams {
+  keyword: string;
+  sort: CollectionSort;
+  page: number;
+  /** True while a param change is re-fetching the server-rendered page
+   *  (this route has no client-side data fetch of its own — every sort/
+   *  search/page change is a real server round-trip). Themes can dim the
+   *  grid on this the same way `useShop`'s client fetch does. */
+  isPending: boolean;
+  setKeyword: (keyword: string) => void;
+  setSort: (sort: CollectionSort) => void;
+  setPage: (page: number) => void;
+}
+
+/**
+ * Collection detail search/sort/page state, persisted in the URL query
+ * string (mirrors `useShopParams` — same mechanism, collection-scoped: no
+ * `category` key since the collection itself is already the scope).
+ *
+ * Query keys: `q` (keyword), `sort`, `page`. Changing keyword or sort resets
+ * to page 1. The matching server route reads these same keys to fetch the
+ * real page — this hook only ever manages the URL, never fetches.
+ */
+export function useCollectionParams(): CollectionParams {
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const [isPending, startTransition] = useTransition();
+
+  const keyword = searchParams.get('q') ?? '';
+  const sortRaw = searchParams.get('sort');
+  const sort: CollectionSort = SORTS.includes(sortRaw as CollectionSort) ? (sortRaw as CollectionSort) : 'newest';
+  const pageRaw = Number(searchParams.get('page'));
+  const page = Number.isFinite(pageRaw) && pageRaw > 1 ? Math.floor(pageRaw) : 1;
+
+  const apply = useCallback(
+    (next: { q?: string | null; sort?: CollectionSort; page?: number }) => {
+      const params = new URLSearchParams(searchParams.toString());
+      const set = (key: string, value: string | null | undefined): void => {
+        if (value === null || value === undefined || value === '') params.delete(key);
+        else params.set(key, value);
+      };
+      if ('q' in next) set('q', next.q);
+      if ('sort' in next) set('sort', next.sort === 'newest' ? null : next.sort);
+      if ('page' in next) set('page', next.page && next.page > 1 ? String(next.page) : null);
+      const qs = params.toString();
+      startTransition(() => {
+        router.replace(qs ? `${pathname}?${qs}` : pathname, { scroll: false });
+      });
+    },
+    [router, pathname, searchParams],
+  );
+
+  const setKeyword = useCallback((value: string) => apply({ q: value.trim() || null, page: 1 }), [apply]);
+  const setSort = useCallback((value: CollectionSort) => apply({ sort: value, page: 1 }), [apply]);
+  const setPage = useCallback((value: number) => apply({ page: value }), [apply]);
+
+  return { keyword, sort, page, isPending, setKeyword, setSort, setPage };
+}

package/hooks/use-href.ts

@@ -0,0 +1,15 @@
+import { useStorefront } from '../provider';
+
+/**
+ * Returns a function that builds storefront-relative hrefs.
+ * On subdomain: href("/shop") → "/shop"
+ * On path-based: href("/shop") → "/vendor-slug/shop"
+ */
+export function useHref() {
+  const { basePath } = useStorefront();
+
+  return (path: string) => {
+    if (!path.startsWith('/')) return path;
+    return `${basePath}${path}`;
+  };
+}

package/hooks/use-posts.ts

@@ -0,0 +1,75 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useStorefront } from '../provider';
+import type { ApiResponse } from '../types/product';
+import type { Post } from '../types/page';
+import { createBrowserClient } from '../sdk/client';
+
+/**
+ * Client-side blog-post listing, for blocks embedded on an arbitrary page
+ * (e.g. the 'blog' home-page block) — mirrors useProducts' shape/pattern.
+ * The blog LISTING page itself (pages/blog.tsx) gets its posts via SSR props
+ * instead (fetchPosts in lib/core/api/pages.ts); this hook is for anywhere
+ * else a theme needs a live post list without page-level SSR data.
+ */
+export function usePosts(options?: { category?: string | null; limit?: number }): { posts: Post[]; isLoading: boolean } {
+  const { previewData, vendor } = useStorefront();
+  const [posts, setPosts] = useState<Post[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    const previewPosts = previewData?.posts;
+
+    async function run(): Promise<void> {
+      setIsLoading(true);
+
+      try {
+        if (Array.isArray(previewPosts)) {
+          let next = [...previewPosts];
+
+          if (options?.category) {
+            next = next.filter((post) => post.blog_categories?.some((category) => category.slug === options.category));
+          }
+
+          if (typeof options?.limit === 'number') {
+            next = next.slice(0, options.limit);
+          }
+
+          if (!cancelled) {
+            setPosts(next);
+          }
+          return;
+        }
+
+        const client = createBrowserClient(vendor.slug ?? undefined);
+        const query: Record<string, string | number> = {};
+        if (options?.category) query.category = options.category;
+        if (options?.limit) query.per_page = options.limit;
+
+        const response = await client.get<ApiResponse<Post[]>>('/posts', query);
+
+        if (!cancelled) {
+          setPosts(response.data ?? []);
+        }
+      } catch {
+        if (!cancelled) {
+          setPosts([]);
+        }
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void run();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [options?.category, options?.limit, previewData?.posts, vendor.slug]);
+
+  return { posts, isLoading };
+}