@growsober/sdk 1.0.0

package/src/api/queries/admin.ts

@@ -0,0 +1,480 @@
+/**
+ * Admin Query Hooks
+ *
+ * TanStack Query hooks for admin-related read operations.
+ * These hooks handle fetching data for the admin dashboard including
+ * users, hubs, events, businesses, content, and analytics.
+ *
+ * @module api/queries/admin
+ */
+
+import { useQuery, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type {
+  UserResponse,
+  HubResponse,
+  EventResponse,
+  BusinessResponse,
+  LibraryContentResponse,
+} from '../types';
+
+// ============================================================================
+// ADMIN TYPES
+// ============================================================================
+
+export interface AdminDashboardStats {
+  totalUsers: number;
+  activeUsers: number;
+  newUsersToday: number;
+  newUsersThisWeek: number;
+  totalHubs: number;
+  totalEvents: number;
+  upcomingEvents: number;
+  totalBusinesses: number;
+  verifiedBusinesses: number;
+  premiumUsers: number;
+  revenue: {
+    today: number;
+    thisWeek: number;
+    thisMonth: number;
+  };
+}
+
+export interface AdminAnalyticsData {
+  period: string;
+  userGrowth: Array<{ date: string; count: number }>;
+  eventAttendance: Array<{ date: string; count: number }>;
+  hubActivity: Array<{ date: string; count: number }>;
+  revenue: Array<{ date: string; amount: number }>;
+  topHubs: Array<{ id: string; name: string; memberCount: number }>;
+  topEvents: Array<{ id: string; title: string; attendeeCount: number }>;
+}
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  meta: {
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+  };
+}
+
+export interface AdminUserFilters {
+  page?: number;
+  limit?: number;
+  search?: string;
+  status?: 'active' | 'suspended' | 'deleted';
+  isPremium?: boolean;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+export interface AdminHubFilters {
+  page?: number;
+  limit?: number;
+  search?: string;
+  status?: 'active' | 'inactive';
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+export interface AdminEventFilters {
+  page?: number;
+  limit?: number;
+  search?: string;
+  status?: 'draft' | 'published' | 'cancelled';
+  hubId?: string;
+  upcoming?: boolean;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+export interface AdminBusinessFilters {
+  page?: number;
+  limit?: number;
+  search?: string;
+  isVerified?: boolean;
+  type?: string;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+export interface AdminContentFilters {
+  page?: number;
+  limit?: number;
+  search?: string;
+  type?: string;
+  category?: string;
+  isFeatured?: boolean;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+export const adminKeys = {
+  all: ['admin'] as const,
+  dashboard: () => [...adminKeys.all, 'dashboard'] as const,
+  analytics: (period?: string) => [...adminKeys.all, 'analytics', period] as const,
+  users: {
+    all: () => [...adminKeys.all, 'users'] as const,
+    list: (filters?: AdminUserFilters) => [...adminKeys.users.all(), 'list', filters] as const,
+    detail: (id: string) => [...adminKeys.users.all(), 'detail', id] as const,
+  },
+  hubs: {
+    all: () => [...adminKeys.all, 'hubs'] as const,
+    list: (filters?: AdminHubFilters) => [...adminKeys.hubs.all(), 'list', filters] as const,
+    detail: (id: string) => [...adminKeys.hubs.all(), 'detail', id] as const,
+  },
+  events: {
+    all: () => [...adminKeys.all, 'events'] as const,
+    list: (filters?: AdminEventFilters) => [...adminKeys.events.all(), 'list', filters] as const,
+    detail: (id: string) => [...adminKeys.events.all(), 'detail', id] as const,
+  },
+  businesses: {
+    all: () => [...adminKeys.all, 'businesses'] as const,
+    list: (filters?: AdminBusinessFilters) =>
+      [...adminKeys.businesses.all(), 'list', filters] as const,
+    detail: (id: string) => [...adminKeys.businesses.all(), 'detail', id] as const,
+  },
+  content: {
+    all: () => [...adminKeys.all, 'content'] as const,
+    list: (filters?: AdminContentFilters) =>
+      [...adminKeys.content.all(), 'list', filters] as const,
+    detail: (id: string) => [...adminKeys.content.all(), 'detail', id] as const,
+  },
+};
+
+// ============================================================================
+// DASHBOARD & ANALYTICS
+// ============================================================================
+
+/**
+ * Get admin dashboard statistics
+ *
+ * @description
+ * Retrieves key metrics for the admin dashboard including
+ * user counts, hub stats, event stats, and revenue data.
+ *
+ * @endpoint GET /api/v1/admin/dashboard
+ *
+ * @example
+ * ```tsx
+ * import { useAdminDashboard } from '@growsober/sdk';
+ *
+ * function AdminDashboard() {
+ *   const { data: stats, isLoading } = useAdminDashboard();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <div>
+ *       <StatCard label="Total Users" value={stats.totalUsers} />
+ *       <StatCard label="Active Users" value={stats.activeUsers} />
+ *       <StatCard label="Premium Users" value={stats.premiumUsers} />
+ *       <StatCard label="Revenue This Month" value={stats.revenue.thisMonth} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useAdminDashboard(
+  options?: Omit<UseQueryOptions<AdminDashboardStats>, 'queryKey' | 'queryFn'>
+): UseQueryResult<AdminDashboardStats> {
+  return useQuery({
+    queryKey: adminKeys.dashboard(),
+    queryFn: async (): Promise<AdminDashboardStats> => {
+      const client = getApiClient();
+      const response = await client.get<AdminDashboardStats>('/api/v1/admin/dashboard');
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get admin analytics data
+ *
+ * @description
+ * Retrieves detailed analytics data for charts and reports.
+ *
+ * @endpoint GET /api/v1/admin/analytics
+ *
+ * @example
+ * ```tsx
+ * import { useAdminAnalytics } from '@growsober/sdk';
+ *
+ * function AnalyticsPage() {
+ *   const { data: analytics } = useAdminAnalytics('30d');
+ *
+ *   return (
+ *     <div>
+ *       <LineChart data={analytics?.userGrowth} />
+ *       <BarChart data={analytics?.eventAttendance} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useAdminAnalytics(
+  period?: string,
+  options?: Omit<UseQueryOptions<AdminAnalyticsData>, 'queryKey' | 'queryFn'>
+): UseQueryResult<AdminAnalyticsData> {
+  return useQuery({
+    queryKey: adminKeys.analytics(period),
+    queryFn: async (): Promise<AdminAnalyticsData> => {
+      const client = getApiClient();
+      const response = await client.get<AdminAnalyticsData>('/api/v1/admin/analytics', {
+        params: { period },
+      });
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+// ============================================================================
+// USER MANAGEMENT
+// ============================================================================
+
+/**
+ * List users for admin
+ *
+ * @endpoint GET /api/v1/admin/users
+ */
+export function useAdminUsers(
+  filters?: AdminUserFilters,
+  options?: Omit<UseQueryOptions<PaginatedResponse<UserResponse>>, 'queryKey' | 'queryFn'>
+): UseQueryResult<PaginatedResponse<UserResponse>> {
+  return useQuery({
+    queryKey: adminKeys.users.list(filters),
+    queryFn: async (): Promise<PaginatedResponse<UserResponse>> => {
+      const client = getApiClient();
+      const response = await client.get<PaginatedResponse<UserResponse>>(
+        '/api/v1/admin/users',
+        { params: filters }
+      );
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get user detail for admin
+ *
+ * @endpoint GET /api/v1/admin/users/{id}
+ */
+export function useAdminUser(
+  id: string,
+  options?: Omit<UseQueryOptions<UserResponse>, 'queryKey' | 'queryFn'>
+): UseQueryResult<UserResponse> {
+  return useQuery({
+    queryKey: adminKeys.users.detail(id),
+    queryFn: async (): Promise<UserResponse> => {
+      const client = getApiClient();
+      const response = await client.get<UserResponse>(`/api/v1/admin/users/${id}`);
+      return response.data;
+    },
+    enabled: !!id,
+    ...options,
+  });
+}
+
+// ============================================================================
+// HUB MANAGEMENT
+// ============================================================================
+
+/**
+ * List hubs for admin
+ *
+ * @endpoint GET /api/v1/admin/hubs
+ */
+export function useAdminHubs(
+  filters?: AdminHubFilters,
+  options?: Omit<UseQueryOptions<PaginatedResponse<HubResponse>>, 'queryKey' | 'queryFn'>
+): UseQueryResult<PaginatedResponse<HubResponse>> {
+  return useQuery({
+    queryKey: adminKeys.hubs.list(filters),
+    queryFn: async (): Promise<PaginatedResponse<HubResponse>> => {
+      const client = getApiClient();
+      const response = await client.get<PaginatedResponse<HubResponse>>(
+        '/api/v1/admin/hubs',
+        { params: filters }
+      );
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get hub detail for admin
+ *
+ * @endpoint GET /api/v1/admin/hubs/{id}
+ */
+export function useAdminHub(
+  id: string,
+  options?: Omit<UseQueryOptions<HubResponse>, 'queryKey' | 'queryFn'>
+): UseQueryResult<HubResponse> {
+  return useQuery({
+    queryKey: adminKeys.hubs.detail(id),
+    queryFn: async (): Promise<HubResponse> => {
+      const client = getApiClient();
+      const response = await client.get<HubResponse>(`/api/v1/admin/hubs/${id}`);
+      return response.data;
+    },
+    enabled: !!id,
+    ...options,
+  });
+}
+
+// ============================================================================
+// EVENT MANAGEMENT
+// ============================================================================
+
+/**
+ * List events for admin
+ *
+ * @endpoint GET /api/v1/admin/events
+ */
+export function useAdminEvents(
+  filters?: AdminEventFilters,
+  options?: Omit<UseQueryOptions<PaginatedResponse<EventResponse>>, 'queryKey' | 'queryFn'>
+): UseQueryResult<PaginatedResponse<EventResponse>> {
+  return useQuery({
+    queryKey: adminKeys.events.list(filters),
+    queryFn: async (): Promise<PaginatedResponse<EventResponse>> => {
+      const client = getApiClient();
+      const response = await client.get<PaginatedResponse<EventResponse>>(
+        '/api/v1/admin/events',
+        { params: filters }
+      );
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get event detail for admin
+ *
+ * @endpoint GET /api/v1/admin/events/{id}
+ */
+export function useAdminEvent(
+  id: string,
+  options?: Omit<UseQueryOptions<EventResponse>, 'queryKey' | 'queryFn'>
+): UseQueryResult<EventResponse> {
+  return useQuery({
+    queryKey: adminKeys.events.detail(id),
+    queryFn: async (): Promise<EventResponse> => {
+      const client = getApiClient();
+      const response = await client.get<EventResponse>(`/api/v1/admin/events/${id}`);
+      return response.data;
+    },
+    enabled: !!id,
+    ...options,
+  });
+}
+
+// ============================================================================
+// BUSINESS MANAGEMENT
+// ============================================================================
+
+/**
+ * List businesses for admin
+ *
+ * @endpoint GET /api/v1/admin/businesses
+ */
+export function useAdminBusinesses(
+  filters?: AdminBusinessFilters,
+  options?: Omit<UseQueryOptions<PaginatedResponse<BusinessResponse>>, 'queryKey' | 'queryFn'>
+): UseQueryResult<PaginatedResponse<BusinessResponse>> {
+  return useQuery({
+    queryKey: adminKeys.businesses.list(filters),
+    queryFn: async (): Promise<PaginatedResponse<BusinessResponse>> => {
+      const client = getApiClient();
+      const response = await client.get<PaginatedResponse<BusinessResponse>>(
+        '/api/v1/admin/businesses',
+        { params: filters }
+      );
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get business detail for admin
+ *
+ * @endpoint GET /api/v1/admin/businesses/{id}
+ */
+export function useAdminBusiness(
+  id: string,
+  options?: Omit<UseQueryOptions<BusinessResponse>, 'queryKey' | 'queryFn'>
+): UseQueryResult<BusinessResponse> {
+  return useQuery({
+    queryKey: adminKeys.businesses.detail(id),
+    queryFn: async (): Promise<BusinessResponse> => {
+      const client = getApiClient();
+      const response = await client.get<BusinessResponse>(`/api/v1/admin/businesses/${id}`);
+      return response.data;
+    },
+    enabled: !!id,
+    ...options,
+  });
+}
+
+// ============================================================================
+// CONTENT MANAGEMENT
+// ============================================================================
+
+/**
+ * List content for admin
+ *
+ * @endpoint GET /api/v1/admin/content
+ */
+export function useAdminContent(
+  filters?: AdminContentFilters,
+  options?: Omit<
+    UseQueryOptions<PaginatedResponse<LibraryContentResponse>>,
+    'queryKey' | 'queryFn'
+  >
+): UseQueryResult<PaginatedResponse<LibraryContentResponse>> {
+  return useQuery({
+    queryKey: adminKeys.content.list(filters),
+    queryFn: async (): Promise<PaginatedResponse<LibraryContentResponse>> => {
+      const client = getApiClient();
+      const response = await client.get<PaginatedResponse<LibraryContentResponse>>(
+        '/api/v1/admin/content',
+        { params: filters }
+      );
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get content detail for admin
+ *
+ * @endpoint GET /api/v1/admin/content/{id}
+ */
+export function useAdminContentItem(
+  id: string,
+  options?: Omit<UseQueryOptions<LibraryContentResponse>, 'queryKey' | 'queryFn'>
+): UseQueryResult<LibraryContentResponse> {
+  return useQuery({
+    queryKey: adminKeys.content.detail(id),
+    queryFn: async (): Promise<LibraryContentResponse> => {
+      const client = getApiClient();
+      const response = await client.get<LibraryContentResponse>(`/api/v1/admin/content/${id}`);
+      return response.data;
+    },
+    enabled: !!id,
+    ...options,
+  });
+}

package/src/api/queries/ambassadors.ts

@@ -0,0 +1,139 @@
+import { useQuery, UseQueryOptions } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type { AmbassadorResponse, AmbassadorLeaderboardResponse, AmbassadorStatus } from '../types';
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+export const ambassadorKeys = {
+  all: ['ambassadors'] as const,
+  lists: () => [...ambassadorKeys.all, 'list'] as const,
+  list: (filters?: AmbassadorListFilters) => [...ambassadorKeys.lists(), filters] as const,
+  details: () => [...ambassadorKeys.all, 'detail'] as const,
+  detail: (id: string) => [...ambassadorKeys.details(), id] as const,
+  me: () => [...ambassadorKeys.all, 'me'] as const,
+  leaderboard: (filters?: LeaderboardFilters) => [...ambassadorKeys.all, 'leaderboard', filters] as const,
+  pending: () => [...ambassadorKeys.all, 'pending'] as const,
+};
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface AmbassadorListFilters {
+  page?: number;
+  limit?: number;
+  hubId?: string;
+  status?: AmbassadorStatus;
+  isVerified?: boolean;
+  isFoundingAmbassador?: boolean;
+}
+
+export interface LeaderboardFilters {
+  limit?: number;
+  hubId?: string;
+}
+
+export interface PaginatedAmbassadorsResponse {
+  ambassadors: AmbassadorResponse[];
+  meta: {
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+  };
+}
+
+// ============================================================================
+// QUERY HOOKS
+// ============================================================================
+
+/**
+ * Get all ambassadors with pagination and filters
+ */
+export function useAmbassadors(
+  filters?: AmbassadorListFilters,
+  options?: Omit<UseQueryOptions<PaginatedAmbassadorsResponse>, 'queryKey' | 'queryFn'>
+) {
+  return useQuery({
+    queryKey: ambassadorKeys.list(filters),
+    queryFn: async (): Promise<PaginatedAmbassadorsResponse> => {
+      const client = getApiClient();
+      const response = await client.get('/api/v1/ambassadors', { params: filters });
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get ambassador by ID
+ */
+export function useAmbassador(
+  id: string,
+  options?: Omit<UseQueryOptions<AmbassadorResponse>, 'queryKey' | 'queryFn'>
+) {
+  return useQuery({
+    queryKey: ambassadorKeys.detail(id),
+    queryFn: async (): Promise<AmbassadorResponse> => {
+      const client = getApiClient();
+      const response = await client.get(`/api/v1/ambassadors/${id}`);
+      return response.data;
+    },
+    enabled: !!id && (options?.enabled !== false),
+    ...options,
+  });
+}
+
+/**
+ * Get current user's ambassador status
+ */
+export function useMyAmbassador(
+  options?: Omit<UseQueryOptions<AmbassadorResponse | null>, 'queryKey' | 'queryFn'>
+) {
+  return useQuery({
+    queryKey: ambassadorKeys.me(),
+    queryFn: async (): Promise<AmbassadorResponse | null> => {
+      const client = getApiClient();
+      const response = await client.get('/api/v1/ambassadors/me');
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get ambassador leaderboard
+ */
+export function useAmbassadorLeaderboard(
+  filters?: LeaderboardFilters,
+  options?: Omit<UseQueryOptions<AmbassadorLeaderboardResponse[]>, 'queryKey' | 'queryFn'>
+) {
+  return useQuery({
+    queryKey: ambassadorKeys.leaderboard(filters),
+    queryFn: async (): Promise<AmbassadorLeaderboardResponse[]> => {
+      const client = getApiClient();
+      const response = await client.get('/api/v1/ambassadors/leaderboard', { params: filters });
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get pending ambassador applications (admin)
+ */
+export function usePendingAmbassadors(
+  options?: Omit<UseQueryOptions<AmbassadorResponse[]>, 'queryKey' | 'queryFn'>
+) {
+  return useQuery({
+    queryKey: ambassadorKeys.pending(),
+    queryFn: async (): Promise<AmbassadorResponse[]> => {
+      const client = getApiClient();
+      const response = await client.get('/api/v1/ambassadors/pending');
+      return response.data;
+    },
+    ...options,
+  });
+}

package/src/api/queries/auth.ts

@@ -0,0 +1,24 @@
+/**
+ * Auth Query Hooks
+ *
+ * TanStack Query hooks for authentication-related read operations.
+ * These hooks handle fetching current user data and managing cache invalidation.
+ *
+ * @module api/queries/auth
+ */
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+/**
+ * Query key factory for auth-related queries
+ * @see https://tkdodo.eu/blog/effective-react-query-keys
+ */
+export const authKeys = {
+  all: ['auth'] as const,
+  me: () => [...authKeys.all, 'me'] as const,
+};
+
+// Note: useCurrentUser is exported from queries/users.ts
+// It uses the /api/v1/users/me endpoint which is the correct endpoint for fetching user data