feat(trails): trail search micro frontend acquisition surface

CLAUDE.md

@@ -96,12 +96,39 @@ features/{name}/
 - **Feature flags**: `apps/expo/config.ts` — `featureFlags` object, default new flags to `false`
 - **Animations**: React Native Reanimated 4
 
-### Web Apps (apps/guides, apps/landing)
+### Web Apps (apps/guides, apps/landing, apps/trails)
 
 - Radix UI + Shadcn components, Tailwind CSS
 - TanStack React Query for data fetching
 - Zod for form validation
 
+### API Client (`@packrat/api-client`)
+
+Use `createApiClient` from `@packrat/api-client` for all PackRat API calls in web apps. **Never write manual fetch wrappers for PackRat API endpoints.**
+
+```ts
+// apps/<name>/lib/apiClient.ts
+import { createApiClient } from '@packrat/api-client';
+import { clearTokens, clearUser, getAccessToken, getRefreshToken, setTokens } from './auth';
+
+export const apiClient = createApiClient({
+  baseUrl: typeof window !== 'undefined' ? window.location.origin : '',
+  auth: {
+    getAccessToken,
+    getRefreshToken,
+    onAccessTokenRefreshed: (token) => { /* persist new access token */ },
+    onRefreshTokenRefreshed: (token) => { /* persist new refresh token */ },
+    onNeedsReauth: () => { clearTokens(); clearUser(); },
+  },
+});
+```
+
+- `baseUrl` should be the same origin when routing through a CF Worker proxy (so rate limiting applies); use `EXPO_PUBLIC_API_URL` for the Expo app
+- `AuthHooks` wires your platform's token storage — the package is transport-only
+- The client handles 401 → refresh → retry automatically; `onNeedsReauth` fires only when refresh itself fails
+- Call via Treaty path syntax: `apiClient.auth.login.post(...)`, `apiClient.trails.search.get({ query: { q } })`
+- Responses are `{ data, error, status }` — check `if (error || !data)` before using `data`
+
 ## Private Package Auth
 
 `@packrat-ai/nativewindui` is hosted on GitHub Packages. `bunfig.toml` resolves the scope using `$PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN`. Bun auto-loads `.env.local` before running `install`, so the simplest setup is to put the token there alongside your other secrets.

apps/admin/lib/auth.ts

@@ -1,19 +1,20 @@
+import { safeSessionStorage } from '@packrat/app/browser';
+
 const TOKEN_KEY = 'packrat_admin_token';
 
 /** Returns the stored admin JWT, or null if not logged in. */
 export function getStoredToken(): string | null {
-  if (typeof window === 'undefined') return null;
-  return sessionStorage.getItem(TOKEN_KEY);
+  return safeSessionStorage.getItem(TOKEN_KEY);
 }
 
 /** Persist a short-lived admin JWT for the session. */
 export function storeToken(token: string): void {
-  sessionStorage.setItem(TOKEN_KEY, token);
+  safeSessionStorage.setItem(TOKEN_KEY, token);
 }
 
 /** Remove the token (logout). */
 export function clearToken(): void {
-  if (typeof window !== 'undefined') sessionStorage.removeItem(TOKEN_KEY);
+  safeSessionStorage.removeItem(TOKEN_KEY);
 }
 
 /** Returns an Authorization header object, or empty object if not logged in. */

apps/admin/package.json

@@ -13,6 +13,7 @@
   "dependencies": {
     "@elysiajs/eden": "catalog:",
     "@packrat/api-client": "workspace:*",
+    "@packrat/app": "workspace:*",
     "@packrat/guards": "workspace:*",
     "@packrat/web-ui": "workspace:*",
     "@radix-ui/react-alert-dialog": "catalog:",

apps/admin/tsconfig.json

@@ -19,6 +19,8 @@
       }
     ],
     "paths": {
+      "@packrat/app": ["../../packages/app/src/index.ts"],
+      "@packrat/app/*": ["../../packages/app/src/*"],
       "admin-app/*": ["./*"],
       "@packrat/api/*": ["../../packages/api/src/*"],
       "@packrat/guards": ["../../packages/guards/src"],

apps/expo/features/auth/hooks/useAuthActions.ts

@@ -1,3 +1,4 @@
+import { UserSchema } from '@packrat/api/schemas/users';
 import { isObject } from '@packrat/guards';
 import AsyncStorage from '@react-native-async-storage/async-storage';
 import {
@@ -6,7 +7,6 @@ import {
   statusCodes,
 } from '@react-native-google-signin/google-signin';
 import { userStore } from 'expo-app/features/auth/store';
-import type { User } from 'expo-app/features/profile/types';
 import { apiClient } from 'expo-app/lib/api/packrat';
 import { t } from 'expo-app/lib/i18n';
 import ImageCacheManager from 'expo-app/lib/utils/ImageCacheManager';
@@ -69,8 +69,7 @@ export function useAuthActions() {
 
       await setToken(data.accessToken);
       await setRefreshToken(data.refreshToken);
-      // safe-cast: Treaty response type differs from local User type; Zod-validated at API boundary
-      userStore.set(data.user as unknown as User);
+      userStore.set(UserSchema.parse(data.user));
 
       setNeedsReauth(false);
       redirect(redirectTo);
@@ -101,8 +100,7 @@ export function useAuthActions() {
 
       await setToken(data.accessToken);
       await setRefreshToken(data.refreshToken);
-      // safe-cast: Treaty response type differs from local User type; Zod-validated at API boundary
-      userStore.set(data.user as unknown as User);
+      userStore.set(UserSchema.parse(data.user));
 
       setNeedsReauth(false);
       redirect(redirectTo);
@@ -149,8 +147,7 @@ export function useAuthActions() {
 
       await setToken(data.accessToken);
       await setRefreshToken(data.refreshToken);
-      // safe-cast: Treaty response type differs from local User type; Zod-validated at API boundary
-      userStore.set(data.user as unknown as User);
+      userStore.set(UserSchema.parse(data.user));
 
       setNeedsReauth(false);
       redirect(redirectTo);
@@ -257,8 +254,7 @@ export function useAuthActions() {
         await Storage.setItem('refresh_token', data.refreshToken);
         await setToken(data.accessToken);
         await setRefreshToken(data.refreshToken);
-        // safe-cast: Treaty response type differs from local User type; Zod-validated at API boundary
-        userStore.set(data.user as unknown as User);
+        userStore.set(UserSchema.parse(data.user));
         redirect(redirectTo);
       }
 

apps/expo/features/catalog/components/CatalogBrowserModal.tsx

@@ -164,8 +164,7 @@ export function CatalogBrowserModal({
   const { recentItems } = useRecentlyUsedCatalogItems();
   const { data: popularData, isLoading: isPopularLoading } = usePopularCatalogItems(8);
 
-  // safe-cast: treaty response shape matches CatalogItem[] as validated by the API schema
-  const popularItems = (popularData?.items ?? []) as CatalogItem[];
+  const popularItems = popularData?.items ?? [];
 
   const {
     data: paginatedData,
@@ -188,12 +187,9 @@ export function CatalogBrowserModal({
     error: searchError,
   } = useVectorSearch({ query: debouncedSearchValue, limit: 20 });
 
-  // safe-cast: treaty response shape matches CatalogItem[] as validated by the API schema
-  const items = (
-    isSearching
-      ? searchResult?.items || []
-      : paginatedData?.pages.flatMap((page) => page.items) || []
-  ) as CatalogItem[]; // safe-cast: treaty response shape matches CatalogItem[]
+  const items = isSearching
+    ? searchResult?.items || []
+    : paginatedData?.pages.flatMap((page) => page.items) || [];
   const isLoading = isSearching ? isSearchLoading : isPaginatedLoading;
   const error = isSearching ? searchError : paginatedError;
 

apps/expo/features/catalog/components/ItemReviews.tsx

@@ -26,7 +26,7 @@ export function ItemReviews({ reviews }: ItemReviewsProps) {
     }));
   };
 
-  const formatDate = (dateString: string) => {
+  const formatDate = (dateString: Date | string) => {
     const date = new Date(dateString);
     return date.toLocaleDateString('en-US', {
       year: 'numeric',

apps/expo/features/catalog/hooks/useCatalogItemDetails.ts

@@ -1,11 +1,12 @@
+import { CatalogItemSchema } from '@packrat/api/schemas/catalog';
 import { useQuery } from '@tanstack/react-query';
 import { apiClient } from 'expo-app/lib/api/packrat';
 import { useAuthenticatedQueryToolkit } from 'expo-app/lib/hooks/useAuthenticatedQueryToolkit';
 
 export const getCatalogItem = async (id: string) => {
   const { data, error } = await apiClient.catalog({ id }).get();
   if (error) throw new Error(`Failed to fetch catalog item: ${error.value}`);
-  return data;
+  return CatalogItemSchema.parse(data);
 };
 
 export function useCatalogItemDetails(id: string) {

apps/expo/features/catalog/hooks/useVectorSearch.ts

@@ -1,3 +1,4 @@
+import { VectorSearchResponseSchema } from '@packrat/api/schemas/catalog';
 import { useQuery } from '@tanstack/react-query';
 import { apiClient } from 'expo-app/lib/api/packrat';
 import { useAuthenticatedQueryToolkit } from 'expo-app/lib/hooks/useAuthenticatedQueryToolkit';
@@ -13,7 +14,7 @@ const vectorSearchApi = async (query: string, limit?: number) => {
     },
   });
   if (error) throw new Error(`Vector search API error: ${error.value}`);
-  return data;
+  return VectorSearchResponseSchema.parse(data);
 };
 
 export const useVectorSearch = ({ query, limit }: { query: string; limit?: number }) => {

apps/expo/features/catalog/screens/CatalogItemsScreen.tsx

@@ -67,14 +67,11 @@ function CatalogItemsScreen() {
     isLoading: isVectorLoading,
     error: vectorError,
   } = useVectorSearch({ query: trimmedQuery, limit: 10 });
-  // safe-cast: treaty response shape matches CatalogItem[] as validated by the API schema
-  const searchResults: CatalogItem[] = (vectorResult?.items ?? []) as unknown as CatalogItem[];
+  const searchResults = vectorResult?.items ?? [];
 
-  const paginatedItems: CatalogItem[] =
-    // safe-cast: treaty response shape matches CatalogItem[] as validated by the API schema
-    ((paginatedData?.pages.flatMap((page) => page.items) ?? []) as CatalogItem[]).filter((item) =>
-      Boolean(item?.id),
-    );
+  const paginatedItems = (paginatedData?.pages.flatMap((page) => page.items) ?? []).filter((item) =>
+    Boolean(item?.id),
+  );
 
   const totalItems = paginatedData?.pages[0]?.totalCount ?? 0;
 

apps/expo/features/catalog/types.ts

@@ -1,99 +1,8 @@
-import type { WeightUnit } from 'expo-app/types';
+import type { CatalogItemSchema } from '@packrat/api/schemas/catalog';
+import type { z } from 'zod';
 import type { PackItemInput } from '../packs/input';
 
-export interface CatalogItemLink {
-  id: string;
-  title: string;
-  url: string;
-  type: 'official' | 'review' | 'guide' | 'purchase' | 'other';
-}
-
-export interface CatalogItemReview {
-  id: string;
-  userId: string;
-  userName: string;
-  userAvatar: string;
-  rating: number;
-  text: string;
-  date: string;
-  helpful: number;
-  verified: boolean;
-}
-
-export interface CatalogItem {
-  id: number;
-  name: string;
-  productUrl: string;
-  sku: string;
-  weight: number;
-  weightUnit: WeightUnit;
-  description?: string | null;
-  categories?: string[] | null;
-  images?: string[] | null;
-  brand?: string | null;
-  model?: string | null;
-  ratingValue?: number | null;
-  color?: string | null;
-  size?: string | null;
-  price?: number | null;
-  availability?: 'in_stock' | 'out_of_stock' | 'preorder' | null;
-  seller?: string | null;
-  productSku?: string | null;
-  material?: string | null;
-  currency?: string | null;
-  condition?: string | null;
-  reviewCount?: number | null;
-  usageCount?: number | null;
-
-  variants?: Array<{
-    attribute: string;
-    values: string[];
-  }> | null;
-
-  techs?: Record<string, string> | null;
-
-  links?: Array<{
-    title: string;
-    url: string;
-  }> | null;
-
-  reviews?: Array<{
-    user_name: string;
-    user_avatar?: string | null;
-    context?: Record<string, string> | null;
-    recommends?: boolean | null;
-    rating: number;
-    title: string;
-    text: string;
-    date: string;
-    images?: string[] | null;
-    upvotes?: number | null;
-    downvotes?: number | null;
-    verified?: boolean | null;
-  }> | null;
-
-  qas?: Array<{
-    question: string;
-    user?: string | null;
-    date: string;
-    answers: Array<{
-      a: string;
-      date: string;
-      user?: string | null;
-      upvotes?: number | null;
-    }>;
-  }> | null;
-
-  faqs?: Array<{
-    question: string;
-    answer: string;
-  }> | null;
-
-  embedding?: number[] | null; // vector(1536)
-
-  createdAt: string;
-  updatedAt: string;
-}
+export type CatalogItem = z.infer<typeof CatalogItemSchema>;
 
 export type CatalogItemWithQuantity = CatalogItem & { quantity?: number };
 
@@ -130,8 +39,14 @@ export interface CatalogItemInput {
   currency?: string;
   condition?: string;
   techs?: Record<string, string>;
-  links?: CatalogItemLink[];
-  reviews?: CatalogItemReview[];
+  links?: Array<{ title: string; url: string }>;
+  reviews?: Array<{
+    user_name: string;
+    rating: number;
+    title: string;
+    text: string;
+    date: string;
+  }>;
 }
 
 export type CatalogItemWithPackItemFields = CatalogItem & Partial<PackItemInput>;

apps/expo/features/pack-templates/components/AddPackTemplateItemActions.tsx

@@ -1,7 +1,7 @@
 import { useActionSheet } from '@expo/react-native-action-sheet';
 import type { BottomSheetModal } from '@gorhom/bottom-sheet';
 import { BottomSheetView } from '@gorhom/bottom-sheet';
-import { isFunction, nullToUndefined } from '@packrat/guards';
+import { isFunction } from '@packrat/guards';
 import { Sheet, Text, useColorScheme } from '@packrat/ui/nativewindui';
 import * as Burnt from 'burnt';
 import { appAlert } from 'expo-app/app/_layout';
@@ -120,10 +120,7 @@ export default React.forwardRef<BottomSheetModal, AddPackTemplateItemActionsProp
 
     const handleCatalogItemsSelected = async (catalogItems: CatalogItem[]) => {
       trackRecentlyUsed(catalogItems);
-      await addItemsToPackTemplate(
-        packTemplateId,
-        catalogItems.map((item) => ({ ...item, description: nullToUndefined(item.description) })),
-      );
+      await addItemsToPackTemplate(packTemplateId, catalogItems);
       const itemWord =
         catalogItems.length === 1 ? t('packTemplates.item') : t('packTemplates.items');
       Burnt.toast({

apps/expo/features/packs/components/AddPackItemActions.tsx

@@ -1,7 +1,7 @@
 import { useActionSheet } from '@expo/react-native-action-sheet';
 import type { BottomSheetModal } from '@gorhom/bottom-sheet';
 import { BottomSheetView } from '@gorhom/bottom-sheet';
-import { isFunction, nullToUndefined } from '@packrat/guards';
+import { isFunction } from '@packrat/guards';
 import { Sheet, Text, useColorScheme } from '@packrat/ui/nativewindui';
 import { Icon } from 'expo-app/components/Icon';
 import { isAuthed } from 'expo-app/features/auth/store';
@@ -109,13 +109,7 @@ export default React.forwardRef<BottomSheetModal, AddPackItemActionsProps>(
       if (catalogItems.length > 0) {
         trackRecentlyUsed(catalogItems);
         try {
-          await addItemsToPack(
-            packId,
-            catalogItems.map((item) => ({
-              ...item,
-              description: nullToUndefined(item.description),
-            })),
-          );
+          await addItemsToPack(packId, catalogItems);
         } catch (error) {
           console.error('Error adding catalog items to pack:', error);
           Alert.alert(t('common.error'), t('catalog.somethingWentWrong'));

apps/expo/features/packs/hooks/useCreatePackItem.ts

@@ -13,7 +13,7 @@ export function useCreatePackItem() {
       const newItem: PackItem = {
         id,
         name: itemData.name,
-        description: itemData.description,
+        description: itemData.description ?? undefined,
         weight: itemData.weight,
         weightUnit: itemData.weightUnit,
         quantity: itemData.quantity,