@growsober/sdk 1.0.0

package/src/api/queries/users.ts

@@ -0,0 +1,393 @@
+/**
+ * Users Query Hooks
+ *
+ * TanStack Query hooks for user-related read operations.
+ * These hooks handle fetching user data, profiles, library items, and subscriptions.
+ *
+ * @module api/queries/users
+ */
+
+import { useQuery, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type {
+  UserResponse,
+  UserPublicResponse,
+  LibraryContentResponse,
+  LibraryProgressResponse,
+  OfferResponse,
+  SubscriptionResponse,
+} from '../types';
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+/**
+ * Query key factory for user-related queries
+ * @see https://tkdodo.eu/blog/effective-react-query-keys
+ */
+export const userKeys = {
+  all: ['users'] as const,
+  me: () => [...userKeys.all, 'me'] as const,
+  detail: (id: string) => [...userKeys.all, 'detail', id] as const,
+  public: (id: string) => [...userKeys.all, 'public', id] as const,
+  library: {
+    all: () => [...userKeys.me(), 'library'] as const,
+    bookmarks: () => [...userKeys.library.all(), 'bookmarks'] as const,
+    progress: () => [...userKeys.library.all(), 'progress'] as const,
+  },
+  offers: {
+    all: () => [...userKeys.me(), 'offers'] as const,
+    redeemed: () => [...userKeys.offers.all(), 'redeemed'] as const,
+  },
+  subscription: () => [...userKeys.me(), 'subscription'] as const,
+};
+
+// ============================================================================
+// QUERY HOOKS
+// ============================================================================
+
+/**
+ * Get current user's profile
+ *
+ * @description
+ * Retrieves the currently authenticated user's complete profile information.
+ * Requires a valid access token to be set via the SDK configuration.
+ *
+ * @endpoint GET /api/v1/users/me
+ *
+ * @example
+ * ```tsx
+ * import { useCurrentUser } from '@growsober/sdk';
+ *
+ * function ProfileScreen() {
+ *   const { data: user, isLoading, error } = useCurrentUser();
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return <Error message={error.message} />;
+ *   if (!user) return <NotFound />;
+ *
+ *   return (
+ *     <div>
+ *       <h1>{user.name}</h1>
+ *       <p>{user.email}</p>
+ *       <p>Sober Since: {user.soberDate}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With custom options:
+ * ```tsx
+ * const { data: user } = useCurrentUser({
+ *   refetchOnMount: false,
+ *   staleTime: 5 * 60 * 1000, // 5 minutes
+ * });
+ * ```
+ *
+ * @param options - TanStack Query options for customizing the query behavior
+ * @returns TanStack Query result with user data
+ */
+export function useCurrentUser(
+  options?: Omit<UseQueryOptions<UserResponse>, 'queryKey' | 'queryFn'>
+): UseQueryResult<UserResponse> {
+  return useQuery({
+    queryKey: userKeys.me(),
+    queryFn: async (): Promise<UserResponse> => {
+      const client = getApiClient();
+      const response = await client.get<UserResponse>('/api/v1/users/me');
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get a specific user's full profile by ID
+ *
+ * @description
+ * Retrieves a user's complete profile information by their ID.
+ * This may include private information depending on the requesting user's permissions.
+ *
+ * @endpoint GET /api/v1/users/{id}
+ *
+ * @example
+ * ```tsx
+ * import { useUser } from '@growsober/sdk';
+ *
+ * function UserProfileScreen({ userId }: { userId: string }) {
+ *   const { data: user, isLoading } = useUser(userId);
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <div>
+ *       <Avatar src={user.avatar} />
+ *       <h1>{user.name}</h1>
+ *       <p>{user.bio}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With conditional fetching:
+ * ```tsx
+ * const { data: user } = useUser(userId, {
+ *   enabled: !!userId, // Only fetch when userId is defined
+ * });
+ * ```
+ *
+ * @param id - The user ID to fetch
+ * @param options - TanStack Query options for customizing the query behavior
+ * @returns TanStack Query result with user data
+ */
+export function useUser(
+  id: string,
+  options?: Omit<UseQueryOptions<UserResponse>, 'queryKey' | 'queryFn'>
+): UseQueryResult<UserResponse> {
+  return useQuery({
+    queryKey: userKeys.detail(id),
+    queryFn: async (): Promise<UserResponse> => {
+      const client = getApiClient();
+      const response = await client.get<UserResponse>(`/api/v1/users/${id}`);
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get a user's public profile by ID
+ *
+ * @description
+ * Retrieves a user's public profile information.
+ * This endpoint returns only publicly visible information and doesn't require authentication.
+ *
+ * @endpoint GET /api/v1/users/{id}/public
+ *
+ * @example
+ * ```tsx
+ * import { usePublicProfile } from '@growsober/sdk';
+ *
+ * function PublicProfileCard({ userId }: { userId: string }) {
+ *   const { data: profile, isLoading } = usePublicProfile(userId);
+ *
+ *   if (isLoading) return <Skeleton />;
+ *
+ *   return (
+ *     <div>
+ *       <Avatar src={profile.avatar} />
+ *       <h2>{profile.displayName}</h2>
+ *       <p>{profile.city}</p>
+ *       {profile.soberSince && (
+ *         <p>Sober since: {new Date(profile.soberSince).toLocaleDateString()}</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param id - The user ID to fetch
+ * @param options - TanStack Query options for customizing the query behavior
+ * @returns TanStack Query result with public profile data
+ */
+export function usePublicProfile(
+  id: string,
+  options?: Omit<UseQueryOptions<UserPublicResponse>, 'queryKey' | 'queryFn'>
+): UseQueryResult<UserPublicResponse> {
+  return useQuery({
+    queryKey: userKeys.public(id),
+    queryFn: async (): Promise<UserPublicResponse> => {
+      const client = getApiClient();
+      const response = await client.get<UserPublicResponse>(`/api/v1/users/${id}/public`);
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get current user's bookmarked library content
+ *
+ * @description
+ * Retrieves all library content (articles, videos, podcasts, etc.) that the user has bookmarked.
+ * This allows users to save content for later reading/viewing.
+ *
+ * @endpoint GET /api/v1/users/me/library/bookmarks
+ *
+ * @example
+ * ```tsx
+ * import { useMyBookmarks } from '@growsober/sdk';
+ *
+ * function BookmarksScreen() {
+ *   const { data: bookmarks, isLoading } = useMyBookmarks();
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       <h1>My Saved Content</h1>
+ *       {bookmarks?.map(content => (
+ *         <ContentCard key={content.id} content={content} />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With auto-refresh:
+ * ```tsx
+ * const { data: bookmarks } = useMyBookmarks({
+ *   refetchInterval: 60000, // Refresh every minute
+ * });
+ * ```
+ *
+ * @param options - TanStack Query options for customizing the query behavior
+ * @returns TanStack Query result with array of bookmarked content
+ */
+export function useMyBookmarks(
+  options?: Omit<UseQueryOptions<LibraryContentResponse[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<LibraryContentResponse[]> {
+  return useQuery({
+    queryKey: userKeys.library.bookmarks(),
+    queryFn: async (): Promise<LibraryContentResponse[]> => {
+      const client = getApiClient();
+      const response = await client.get<LibraryContentResponse[]>('/api/v1/users/me/library/bookmarks');
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get current user's library content progress
+ *
+ * @description
+ * Retrieves the user's progress on library content items.
+ * Tracks which content has been started, completed, or partially viewed/read.
+ *
+ * @endpoint GET /api/v1/users/me/library/progress
+ *
+ * @example
+ * ```tsx
+ * import { useMyProgress } from '@growsober/sdk';
+ *
+ * function LibraryProgressScreen() {
+ *   const { data: progress, isLoading } = useMyProgress();
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   const completed = progress?.filter(p => p.completed) || [];
+ *   const inProgress = progress?.filter(p => !p.completed && p.progress > 0) || [];
+ *
+ *   return (
+ *     <div>
+ *       <h2>Completed: {completed.length}</h2>
+ *       <h2>In Progress: {inProgress.length}</h2>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Check progress for specific content:
+ * ```tsx
+ * function ContentProgress({ contentId }: { contentId: string }) {
+ *   const { data: progress } = useMyProgress();
+ *   const contentProgress = progress?.find(p => p.contentId === contentId);
+ *
+ *   return (
+ *     <ProgressBar
+ *       value={contentProgress?.progress || 0}
+ *       max={100}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param options - TanStack Query options for customizing the query behavior
+ * @returns TanStack Query result with array of progress records
+ */
+export function useMyProgress(
+  options?: Omit<UseQueryOptions<LibraryProgressResponse[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<LibraryProgressResponse[]> {
+  return useQuery({
+    queryKey: userKeys.library.progress(),
+    queryFn: async (): Promise<LibraryProgressResponse[]> => {
+      const client = getApiClient();
+      const response = await client.get<LibraryProgressResponse[]>('/api/v1/users/me/library/progress');
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get current user's redeemed offers
+ *
+ * @description
+ * Retrieves all offers/deals that the user has redeemed.
+ * Shows history of partner offers used by the user.
+ *
+ * @endpoint GET /api/v1/users/me/offers/redeemed
+ *
+ * @example
+ * ```tsx
+ * import { useMyRedeemedOffers } from '@growsober/sdk';
+ *
+ * function RedeemedOffersScreen() {
+ *   const { data: offers, isLoading } = useMyRedeemedOffers();
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       <h1>My Redeemed Offers</h1>
+ *       {offers?.map(offer => (
+ *         <div key={offer.id}>
+ *           <h3>{offer.title}</h3>
+ *           <p>Redeemed: {new Date(offer.redeemedAt).toLocaleDateString()}</p>
+ *           <p>Code: {offer.code}</p>
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Check if specific offer was redeemed:
+ * ```tsx
+ * function OfferCard({ offerId }: { offerId: string }) {
+ *   const { data: redeemedOffers } = useMyRedeemedOffers();
+ *   const isRedeemed = redeemedOffers?.some(o => o.id === offerId);
+ *
+ *   return (
+ *     <button disabled={isRedeemed}>
+ *       {isRedeemed ? 'Already Redeemed' : 'Redeem Offer'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @param options - TanStack Query options for customizing the query behavior
+ * @returns TanStack Query result with array of redeemed offers
+ */
+export function useMyRedeemedOffers(
+  options?: Omit<UseQueryOptions<OfferResponse[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<OfferResponse[]> {
+  return useQuery({
+    queryKey: userKeys.offers.redeemed(),
+    queryFn: async (): Promise<OfferResponse[]> => {
+      const client = getApiClient();
+      const response = await client.get<OfferResponse[]>('/api/v1/users/me/offers/redeemed');
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+// Note: useMySubscription is available from '@growsober/sdk' via ./subscriptions