@usequeek/theme-kit 0.1.23 → 0.1.25

package/hooks/use-auth-flow.tsx

@@ -2,7 +2,7 @@
 
 import type { JSX } from 'react';
 import { createContext, useContext, useState, type ReactNode } from 'react';
-import { QueekSdkError, type EmailVerifyOtpResponse } from '@queekai/client-sdk';
+import { QueekSdkError, type EmailVerifyOtpResponse } from '@usequeek/client-sdk';
 import { useStorefront, useThemeStrings } from '../provider';
 import { getQueekClient, setAuthTokens, QUEEK_AUTH_URL } from '../sdk/queek-client';
 import { useAuthModalStore } from '../stores/auth-modal-store';
@@ -246,14 +246,9 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
       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}).`);
+        throw new Error(`The Queek sign-in service answered HTTP ${res.status} when starting Google sign-in. Retry, or use email sign-in.`);
       }
       // Response envelope: { status, message, data: { url } }
       const body = (await res.json()) as {
@@ -266,13 +261,11 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
       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.');
+        throw new Error('The Queek sign-in service did not return a Google redirect URL.');
       }
     } catch (err) {
-      // eslint-disable-next-line no-console
-      console.error('[google-auth] initiate failed', err);
+      // The shopper sees the translated message; the cause stays in the console for the theme developer.
+      console.error('[theme-kit] could not start Google sign-in:', err);
       setError(t('auth.error.google'));
     } finally {
       setLoading(false);
@@ -342,7 +335,9 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
 export function useAuthFlow(): AuthFlowValue {
   const ctx = useContext(AuthFlowContext);
   if (!ctx) {
-    throw new Error('useAuthFlow must be used within an AuthFlowProvider');
+    throw new Error(
+      'useAuthFlow() was called outside <AuthFlowProvider>. Render the auth step components inside <AuthFlow> (or wrap them in <AuthFlowProvider>).',
+    );
   }
   return ctx;
 }

package/hooks/use-auth.ts

@@ -3,6 +3,16 @@
 import { useAuthModalStore } from '../stores/auth-modal-store';
 import { useUserStore } from '../stores/user-store';
 
+/**
+ * The signed-in customer and the sign-in modal controls.
+ *
+ * `user` is null and `isAuthenticated` false until the shopper signs in.
+ * `openAuthModal('signup')` opens the kit's sign-in flow on the sign-up step.
+ *
+ * @example
+ * const { user, isAuthenticated, openAuthModal, logout } = useAuth();
+ * return isAuthenticated ? <button onClick={logout}>Sign out</button> : <button onClick={() => openAuthModal()}>Sign in</button>;
+ */
 export function useAuth() {
   return {
     user: useUserStore((state) => state.user),

package/hooks/use-cart.ts

@@ -2,6 +2,18 @@
 
 import { useCartStore } from '../stores/cart-store';
 
+/**
+ * The shopper's cart and the actions that change it. The cart is kept in the
+ * browser (per sales channel) and survives a reload. `addProduct` refuses a
+ * product that needs a variant when none is given and tells the shopper to
+ * choose an option; otherwise it adds the line and shows an "Added to cart" toast.
+ *
+ * Use {@link useShopCart} for the lines and totals of a single shop.
+ *
+ * @example
+ * const { items, addProduct, setQuantity } = useCart();
+ * <button onClick={() => addProduct(product, 1, matchedVariant)}>Add to cart</button>
+ */
 export function useCart() {
   return {
     items: useCartStore((state) => state.items),

package/hooks/use-categories.ts

@@ -4,6 +4,7 @@ import { useEffect, useState } from 'react';
 import { useStorefront, useStorefrontLocale } from '../provider';
 import { createBrowserClient } from '../sdk/client';
 import { withLocaleQuery } from '../utils/locale';
+import { toError } from '../utils/to-error';
 
 export interface Category {
   id: string;
@@ -37,17 +38,28 @@ function flattenCategories(items: Category[]): Category[] {
   return out;
 }
 
+/**
+ * The store's categories (collections), flattened from any depth. Pass `ids`
+ * to pick specific ones, kept in the order you gave; pass `limit` to cap the
+ * count. On failure the list is empty and `error` is set; the hook never
+ * throws.
+ *
+ * @example
+ * const { categories } = useCategories({ limit: 6 });
+ */
 export function useCategories(options?: {
   ids?: string[];
   limit?: number;
 }): {
   categories: Category[];
   isLoading: boolean;
+  error: Error | null;
 } {
   const { previewData, vendor } = useStorefront();
   const locale = useStorefrontLocale();
   const [categories, setCategories] = useState<Category[]>([]);
   const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
 
   const idsKey = options?.ids?.join(',') ?? '';
   const limit = options?.limit;
@@ -59,6 +71,7 @@ export function useCategories(options?: {
 
     async function run(): Promise<void> {
       setIsLoading(true);
+      setError(null);
 
       try {
         if (Array.isArray(previewCategories)) {
@@ -95,9 +108,10 @@ export function useCategories(options?: {
           setCategories(typeof limit === 'number' ? items.slice(0, limit) : items);
           setIsLoading(false);
         }
-      } catch {
+      } catch (caught) {
         if (!cancelled) {
           setCategories([]);
+          setError(toError(caught));
           setIsLoading(false);
         }
       }
@@ -110,5 +124,5 @@ export function useCategories(options?: {
     };
   }, [idsKey, limit, previewData?.categories, vendor.slug, locale]);
 
-  return { categories, isLoading };
+  return { categories, isLoading, error };
 }

package/hooks/use-href.ts

@@ -1,11 +1,16 @@
 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"
+ * Returns a function that turns a store path into a link target. A store served
+ * on its own domain keeps `/shop` as `/shop`; a store served under a path
+ * prefix gets `/<store-slug>/shop`. Anything that does not start with `/`
+ * (a full URL, `#anchor`, `mailto:`) is returned unchanged.
+ *
+ * @example
+ * const href = useHref();
+ * <Link href={href('/shop')}>Shop</Link>
  */
-export function useHref() {
+export function useHref(): (path: string) => string {
   const { basePath } = useStorefront();
 
   return (path: string) => {

package/hooks/use-posts.ts

@@ -6,19 +6,25 @@ import type { ApiResponse } from '../types/product';
 import type { Post } from '../types/page';
 import { createBrowserClient } from '../sdk/client';
 import { withLocaleQuery } from '../utils/locale';
+import { toError } from '../utils/to-error';
 
 /**
- * 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 the host's page loader); this hook is for anywhere
- * else a theme needs a live post list without page-level SSR data.
+ * A live list of blog posts, for a block on any page (such as the home page
+ * `blog` block). Takes the same shape as {@link useProducts}: `isLoading`,
+ * plus `error` when the request fails.
+ *
+ * The blog listing page itself receives its posts as server-rendered props;
+ * use this hook everywhere else a theme needs posts without page-level data.
+ *
+ * @example
+ * const { posts, isLoading } = usePosts({ category: 'news', limit: 3 });
  */
-export function usePosts(options?: { category?: string | null; limit?: number }): { posts: Post[]; isLoading: boolean } {
+export function usePosts(options?: { category?: string | null; limit?: number }): { posts: Post[]; isLoading: boolean; error: Error | null } {
   const { previewData, vendor } = useStorefront();
   const locale = useStorefrontLocale();
   const [posts, setPosts] = useState<Post[]>([]);
   const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
 
   useEffect(() => {
     let cancelled = false;
@@ -26,6 +32,7 @@ export function usePosts(options?: { category?: string | null; limit?: number })
 
     async function run(): Promise<void> {
       setIsLoading(true);
+      setError(null);
 
       try {
         if (Array.isArray(previewPosts)) {
@@ -55,9 +62,10 @@ export function usePosts(options?: { category?: string | null; limit?: number })
         if (!cancelled) {
           setPosts(response.data ?? []);
         }
-      } catch {
+      } catch (caught) {
         if (!cancelled) {
           setPosts([]);
+          setError(toError(caught));
         }
       } finally {
         if (!cancelled) {
@@ -73,5 +81,5 @@ export function usePosts(options?: { category?: string | null; limit?: number })
     };
   }, [options?.category, options?.limit, previewData?.posts, vendor.slug, locale]);
 
-  return { posts, isLoading };
+  return { posts, isLoading, error };
 }

package/hooks/use-product-detail.ts

@@ -4,6 +4,7 @@ import { useEffect, useState } from 'react';
 import { getQueekClient } from '../sdk/queek-client';
 import { withLocalePath } from '../utils/locale';
 import { normalizeProduct } from '../utils/product-normalizer';
+import { toError } from '../utils/to-error';
 import type { Product, LegacyProductLike } from '../types/product';
 
 interface UseProductDetailResult {
@@ -11,18 +12,26 @@ interface UseProductDetailResult {
   product: Product | null;
   /** True only while a fetch the caller should show a loading state for is in flight. */
   loadingDetail: boolean;
+  /** The last detail request's failure, or null. `product` is still the list product then. */
+  error: Error | null;
 }
 
 /**
- * The product LIST/collection endpoint never returns `addons`, `options`, or
- * `variants` — those only exist on the single-product "view" response.
- * Any quick-view/quick-add modal opened from a product card only has the
- * list-shaped object, so it must re-fetch full detail before it can render
- * or select an addon/option — rendering `listProduct.addons` directly always
- * shows nothing, regardless of CSS or wiring.
+ * Complete a product you already hold from a list. The list and collection
+ * endpoints never return `addons`, `options` or `variants`; only the
+ * single-product response has them. A quick-view or quick-add modal opened
+ * from a product card must therefore fetch the full product before it can
+ * show or select an add-on or option.
  *
- * `isOpen` gates the fetch so a modal closed and reopened on a different
- * product re-fetches instead of showing stale detail.
+ * `isOpen` gates the fetch, so a modal closed and reopened on another product
+ * fetches again instead of showing stale detail. `product` is `listProduct`
+ * until the full product arrives, and stays `listProduct` if the request fails
+ * (see `error`).
+ *
+ * For a product you only know by slug, use `useProductBySlug`.
+ *
+ * @example
+ * const { product, loadingDetail } = useProductDetail(card, isModalOpen, vendor.slug, useStorefrontLocale());
  */
 export function useProductDetail(
   listProduct: Product | null,
@@ -39,15 +48,18 @@ export function useProductDetail(
 ): UseProductDetailResult {
   const [fullProduct, setFullProduct] = useState<Product | null>(null);
   const [loadingDetail, setLoadingDetail] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
 
   useEffect(() => {
     if (!isOpen || !listProduct) {
       setFullProduct(null);
       setLoadingDetail(false);
+      setError(null);
       return;
     }
 
     let cancelled = false;
+    setError(null);
     const needsDetail = listProduct.variants_count > 0 || listProduct.addons.length > 0;
     if (needsDetail) {
       setLoadingDetail(true);
@@ -55,7 +67,7 @@ export function useProductDetail(
 
     const client = getQueekClient(vendorSlug ?? undefined);
     client
-      .get<{ data?: LegacyProductLike } | LegacyProductLike>(withLocalePath(`/client/store/products/${listProduct.slug}`, locale))
+      .get<{ data?: LegacyProductLike } | LegacyProductLike>(withLocalePath(`/client/store/products/${encodeURIComponent(listProduct.slug)}`, locale))
       .then((res) => {
         if (cancelled) return;
         const raw = (res as { data?: LegacyProductLike })?.data ?? res;
@@ -63,7 +75,9 @@ export function useProductDetail(
           setFullProduct(normalizeProduct(raw as LegacyProductLike));
         }
       })
-      .catch(() => {})
+      .catch((caught: unknown) => {
+        if (!cancelled) setError(toError(caught));
+      })
       .finally(() => {
         if (!cancelled) setLoadingDetail(false);
       });
@@ -73,5 +87,5 @@ export function useProductDetail(
     };
   }, [isOpen, listProduct, vendorSlug, locale]);
 
-  return { product: fullProduct ?? listProduct, loadingDetail };
+  return { product: fullProduct ?? listProduct, loadingDetail, error };
 }

package/hooks/use-product-questions.ts

@@ -4,6 +4,7 @@ import { useEffect, useState } from 'react';
 import { useStorefront, useStorefrontLocale } from '../provider';
 import { createBrowserClient } from '../sdk/client';
 import { withLocaleQuery } from '../utils/locale';
+import { toError } from '../utils/to-error';
 import type { ProductQaBlockData, ProductQuestionItem } from '../types/block';
 
 interface ProductQuestionsResponse {
@@ -16,14 +17,24 @@ interface ProductQuestionsResponse {
   next_cursor?: string | null;
 }
 
+/**
+ * Published questions and answers for one product, for a `product-qa` block.
+ * Returns no questions when the block has no `product_slug`. On failure the
+ * list is empty and `error` is set; the hook never throws.
+ *
+ * @example
+ * const { questions, isLoading } = useProductQuestions({ product_slug: 'oak-chair', limit: 5 });
+ */
 export function useProductQuestions(options: ProductQaBlockData): {
   questions: ProductQuestionItem[];
   isLoading: boolean;
+  error: Error | null;
 } {
   const { vendor, previewData } = useStorefront();
   const locale = useStorefrontLocale();
   const [questions, setQuestions] = useState<ProductQuestionItem[]>(options._preview?.questions ?? []);
   const [isLoading, setIsLoading] = useState(!options._preview && !previewData);
+  const [error, setError] = useState<Error | null>(null);
 
   const { product_slug, limit } = options;
 
@@ -51,17 +62,19 @@ export function useProductQuestions(options: ProductQaBlockData): {
 
     async function run(): Promise<void> {
       setIsLoading(true);
+      setError(null);
       try {
         const response = await client.get<ProductQuestionsResponse>(
-          `/products/${product_slug}/questions`,
+          `/products/${encodeURIComponent(product_slug)}/questions`,
           withLocaleQuery(query, locale),
         );
         if (!cancelled) {
           setQuestions(response.data.questions ?? []);
         }
-      } catch {
+      } catch (caught) {
         if (!cancelled) {
           setQuestions([]);
+          setError(toError(caught));
         }
       } finally {
         if (!cancelled) setIsLoading(false);
@@ -76,5 +89,5 @@ export function useProductQuestions(options: ProductQaBlockData): {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [vendor.slug, previewData, product_slug, limit, locale]);
 
-  return { questions, isLoading };
+  return { questions, isLoading, error };
 }

package/hooks/use-products.ts

@@ -7,8 +7,10 @@ import type { ApiResponse, LegacyProductLike, ProductListMeta } from '../types/p
 import { createBrowserClient } from '../sdk/client';
 import { withLocaleQuery } from '../utils/locale';
 import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
+import { toError } from '../utils/to-error';
 
-type ProductQuery = {
+/** Filters for {@link useProducts}. */
+export type ProductQuery = {
   collection?: string | null;
   ids?: string[];
   limit?: number;
@@ -42,15 +44,29 @@ function resolvePreviewProducts(products: Product[], options: ProductQuery): Pro
   return typeof options.limit === 'number' ? next.slice(0, options.limit) : next;
 }
 
+/**
+ * A list of the store's products, fetched in the browser (or filtered from the
+ * seeded catalogue in preview).
+ *
+ * Pass `undefined` instead of an options object when the caller already holds
+ * the products: the hook then does nothing and reports `isLoading: false`.
+ * On failure the products already shown are kept and `error` is set; the hook
+ * never throws.
+ *
+ * @example
+ * const { products, isLoading, error } = useProducts({ collection: 'chairs', limit: 8, sort: 'popular' });
+ * if (error) return <p>We could not load products. Try again.</p>;
+ */
 export function useProducts(options?: ProductQuery & {
   /** Backs the "video showcase" products variant. Deliberately incompatible
    *  with `collection` (that path calls a different, collection-scoped
    *  endpoint this filter isn't wired into) — has_video is ignored whenever
    *  collection is also set. */
   hasVideo?: boolean;
-}): { products: Product[]; isLoading: boolean } {
+}): { products: Product[]; isLoading: boolean; error: Error | null } {
   const { previewData, vendor } = useStorefront();
   const locale = useStorefrontLocale();
+  const [error, setError] = useState<Error | null>(null);
   const hasPreviewProducts = Array.isArray(previewData?.products);
   const [products, setProducts] = useState<Product[]>(() => (
     options && hasPreviewProducts ? resolvePreviewProducts(previewData.products!, options) : []
@@ -88,12 +104,13 @@ export function useProducts(options?: ProductQuery & {
         }
 
         setIsLoading(true);
+        setError(null);
 
         let resolvedProducts: Product[];
 
         if (options?.collection) {
           const response = await client.get<ApiResponse<unknown>>(
-            `/collections/${options.collection}/products`,
+            `/collections/${encodeURIComponent(options.collection)}/products`,
             withLocaleQuery(undefined, locale),
           );
           resolvedProducts = extractProducts(response.data).map((p) => normalizeProduct(p));
@@ -129,6 +146,10 @@ export function useProducts(options?: ProductQuery & {
         if (!cancelled) {
           setProducts(next);
         }
+      } catch (caught) {
+        // Keep the products already on screen; surface the failure instead of
+        // leaving an unhandled rejection.
+        if (!cancelled) setError(toError(caught));
       } finally {
         if (!cancelled) {
           setIsLoading(false);
@@ -143,31 +164,30 @@ export function useProducts(options?: ProductQuery & {
     };
   }, [hasOptions, options?.collection, options?.ids, options?.limit, options?.sort, options?.hasVideo, previewData?.products, vendor.slug, locale]);
 
-  return { products, isLoading };
+  return { products, isLoading, error };
 }
 
 /**
- * Full product detail (the same `/products/{slug}` request the PDP itself
- * uses), including the full ordered detail `media.images` list — the
- * list/collection endpoints `useProducts` calls only ever return a capped
- * `media.images` list plus `media.{image,thumbnail}`. Single-product spotlight
- * blocks (e.g. a `featured` variant) need this instead of substituting
- * image/thumbnail as a fake 2-image list.
- */
-/**
- * Fetch one product by SLUG.
+ * Fetch one product by slug: the same `/products/{slug}` request the product
+ * page uses, including the full ordered `media.images` list. The list
+ * endpoints behind {@link useProducts} return only a capped image list, so a
+ * single-product spotlight block needs this hook instead.
+ *
+ * Different from `useProductDetail` (hooks/use-product-detail.ts), which
+ * completes a product you already hold from a list. Pass `null` or
+ * `undefined` to skip the request. `product` is null while loading, when the
+ * product does not exist, and when the request failed (`error` tells the last
+ * two apart).
  *
- * Distinct from `useProductDetail` in hooks/use-product-detail.ts, which
- * enriches a product you ALREADY hold from a list payload (that one takes the
- * list product, an enabled flag and a vendor slug). Both were called
- * `useProductDetail` until the public surface was written down and the clash
- * surfaced — same name, unrelated signatures, one import path apart.
+ * @example
+ * const { product, isLoading, error } = useProductBySlug('oak-chair');
  */
-export function useProductBySlug(slug: string | null | undefined): { product: Product | null; isLoading: boolean } {
+export function useProductBySlug(slug: string | null | undefined): { product: Product | null; isLoading: boolean; error: Error | null } {
   const { previewData, vendor } = useStorefront();
   const locale = useStorefrontLocale();
   const [product, setProduct] = useState<Product | null>(null);
   const [isLoading, setIsLoading] = useState(!!slug);
+  const [error, setError] = useState<Error | null>(null);
 
   useEffect(() => {
     if (!slug) {
@@ -190,16 +210,18 @@ export function useProductBySlug(slug: string | null | undefined): { product: Pr
 
     async function run(): Promise<void> {
       setIsLoading(true);
+      setError(null);
       try {
-        const response = await client.get<ApiResponse<LegacyProductLike>>(`/products/${slug}`, withLocaleQuery(undefined, locale));
+        const response = await client.get<ApiResponse<LegacyProductLike>>(`/products/${encodeURIComponent(slug as string)}`, withLocaleQuery(undefined, locale));
         const products = extractProducts(response.data);
         const payload = products[0] ?? response.data;
         if (!cancelled) {
           setProduct(payload ? normalizeProduct(payload as LegacyProductLike) : null);
         }
-      } catch {
+      } catch (caught) {
         if (!cancelled) {
           setProduct(null);
+          setError(toError(caught));
         }
       } finally {
         if (!cancelled) {
@@ -215,5 +237,5 @@ export function useProductBySlug(slug: string | null | undefined): { product: Pr
     };
   }, [slug, previewData?.products, vendor.slug, locale]);
 
-  return { product, isLoading };
+  return { product, isLoading, error };
 }

package/hooks/use-related-products.ts

@@ -7,21 +7,32 @@ import type { ApiResponse } from '../types/product';
 import { createBrowserClient } from '../sdk/client';
 import { withLocaleQuery } from '../utils/locale';
 import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
+import { toError } from '../utils/to-error';
 
+/**
+ * Products related to the one being viewed (up to `limit`, default 4). The
+ * list stays empty when the request fails; `error` tells you why, and a theme
+ * can simply hide the section.
+ *
+ * @example
+ * const { products } = useRelatedProducts(product.slug, 4);
+ */
 export function useRelatedProducts(
   currentSlug: string,
   limit = 4,
-): { products: Product[]; isLoading: boolean } {
+): { products: Product[]; isLoading: boolean; error: Error | null } {
   const { vendor, previewData } = useStorefront();
   const locale = useStorefrontLocale();
   const [products, setProducts] = useState<Product[]>([]);
   const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
 
   useEffect(() => {
     let cancelled = false;
 
     async function run(): Promise<void> {
       setIsLoading(true);
+      setError(null);
       try {
         if (previewData?.products) {
           const others = (previewData.products as Product[])
@@ -33,7 +44,7 @@ export function useRelatedProducts(
 
         const client = createBrowserClient(vendor.slug ?? undefined);
         const response = await client.get<ApiResponse<unknown>>(
-          `/products/${currentSlug}/related`,
+          `/products/${encodeURIComponent(currentSlug)}/related`,
           withLocaleQuery({ limit }, locale),
         );
 
@@ -43,8 +54,9 @@ export function useRelatedProducts(
           .slice(0, limit);
 
         if (!cancelled) setProducts(normalized);
-      } catch {
-        // Non-critical — silently fail
+      } catch (caught) {
+        // Non-critical: the section can hide itself. The failure is on `error`.
+        if (!cancelled) setError(toError(caught));
       } finally {
         if (!cancelled) setIsLoading(false);
       }
@@ -54,5 +66,5 @@ export function useRelatedProducts(
     return () => { cancelled = true; };
   }, [currentSlug, limit, vendor.slug, previewData?.products, locale]);
 
-  return { products, isLoading };
+  return { products, isLoading, error };
 }

package/hooks/use-resolve-coordinates.ts

@@ -14,6 +14,15 @@ interface CoordinatesResponse {
   state_id?: string | null;
 }
 
+/**
+ * Turns a chosen address suggestion into coordinates and saves it as the
+ * shopper's delivery location. `resolve` returns true when a location was
+ * saved and false when the API gave no usable position or the request failed.
+ *
+ * @example
+ * const { resolve, resolving } = useResolveCoordinates();
+ * const ok = await resolve(suggestion.place_id, suggestion.description);
+ */
 export function useResolveCoordinates(): {
   resolve: (placeId: string, description: string) => Promise<boolean>;
   resolving: boolean;