@growsober/sdk 1.0.0

package/src/api/mutations/ambassadors.ts

@@ -0,0 +1,185 @@
+import {
+  useMutation,
+  useQueryClient,
+  UseMutationOptions,
+  UseMutationResult,
+} from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type { AmbassadorResponse, ApplyAmbassadorRequest, UpdateAmbassadorRequest } from '../types';
+import { ambassadorKeys } from '../queries/ambassadors';
+
+// ============================================================================
+// MUTATION HOOKS
+// ============================================================================
+
+/**
+ * Apply to become an ambassador
+ */
+export function useApplyAmbassador(
+  options?: Omit<
+    UseMutationOptions<AmbassadorResponse, Error, ApplyAmbassadorRequest>,
+    'mutationFn'
+  >
+): UseMutationResult<AmbassadorResponse, Error, ApplyAmbassadorRequest> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: ApplyAmbassadorRequest): Promise<AmbassadorResponse> => {
+      const client = getApiClient();
+      const response = await client.post('/api/v1/ambassadors/apply', data);
+      return response.data;
+    },
+    onSuccess: (ambassador) => {
+      queryClient.setQueryData(ambassadorKeys.me(), ambassador);
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.lists() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Update own ambassador profile
+ */
+export function useUpdateMyAmbassador(
+  options?: Omit<
+    UseMutationOptions<AmbassadorResponse, Error, Partial<UpdateAmbassadorRequest>>,
+    'mutationFn'
+  >
+): UseMutationResult<AmbassadorResponse, Error, Partial<UpdateAmbassadorRequest>> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: Partial<UpdateAmbassadorRequest>): Promise<AmbassadorResponse> => {
+      const client = getApiClient();
+      const response = await client.put('/api/v1/ambassadors/me', data);
+      return response.data;
+    },
+    onSuccess: (ambassador) => {
+      queryClient.setQueryData(ambassadorKeys.me(), ambassador);
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.lists() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Update ambassador (admin)
+ */
+export function useUpdateAmbassador(
+  options?: Omit<
+    UseMutationOptions<AmbassadorResponse, Error, { id: string; data: UpdateAmbassadorRequest }>,
+    'mutationFn'
+  >
+): UseMutationResult<AmbassadorResponse, Error, { id: string; data: UpdateAmbassadorRequest }> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({ id, data }): Promise<AmbassadorResponse> => {
+      const client = getApiClient();
+      const response = await client.put(`/api/v1/ambassadors/${id}`, data);
+      return response.data;
+    },
+    onSuccess: (ambassador, { id }) => {
+      queryClient.setQueryData(ambassadorKeys.detail(id), ambassador);
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.lists() });
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.pending() });
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.leaderboard() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Approve ambassador application (admin)
+ */
+export function useApproveAmbassador(
+  options?: Omit<UseMutationOptions<AmbassadorResponse, Error, string>, 'mutationFn'>
+): UseMutationResult<AmbassadorResponse, Error, string> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (id: string): Promise<AmbassadorResponse> => {
+      const client = getApiClient();
+      const response = await client.post(`/api/v1/ambassadors/${id}/approve`);
+      return response.data;
+    },
+    onSuccess: (ambassador, id) => {
+      queryClient.setQueryData(ambassadorKeys.detail(id), ambassador);
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.lists() });
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.pending() });
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.leaderboard() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Reject ambassador application (admin)
+ */
+export function useRejectAmbassador(
+  options?: Omit<UseMutationOptions<{ success: boolean }, Error, string>, 'mutationFn'>
+): UseMutationResult<{ success: boolean }, Error, string> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (id: string): Promise<{ success: boolean }> => {
+      const client = getApiClient();
+      const response = await client.post(`/api/v1/ambassadors/${id}/reject`);
+      return response.data;
+    },
+    onSuccess: (_, id) => {
+      queryClient.removeQueries({ queryKey: ambassadorKeys.detail(id) });
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.lists() });
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.pending() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Deactivate ambassador (admin)
+ */
+export function useDeactivateAmbassador(
+  options?: Omit<UseMutationOptions<AmbassadorResponse, Error, string>, 'mutationFn'>
+): UseMutationResult<AmbassadorResponse, Error, string> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (id: string): Promise<AmbassadorResponse> => {
+      const client = getApiClient();
+      const response = await client.post(`/api/v1/ambassadors/${id}/deactivate`);
+      return response.data;
+    },
+    onSuccess: (ambassador, id) => {
+      queryClient.setQueryData(ambassadorKeys.detail(id), ambassador);
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.lists() });
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.leaderboard() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Add reward points to ambassador (admin)
+ */
+export function useAddAmbassadorReward(
+  options?: Omit<
+    UseMutationOptions<{ success: boolean }, Error, { id: string; points: number; reason?: string }>,
+    'mutationFn'
+  >
+): UseMutationResult<{ success: boolean }, Error, { id: string; points: number; reason?: string }> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({ id, points, reason }): Promise<{ success: boolean }> => {
+      const client = getApiClient();
+      const response = await client.post(`/api/v1/ambassadors/${id}/reward`, { points, reason });
+      return response.data;
+    },
+    onSuccess: (_, { id }) => {
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.detail(id) });
+      queryClient.invalidateQueries({ queryKey: ambassadorKeys.leaderboard() });
+    },
+    ...options,
+  });
+}

package/src/api/mutations/auth.ts

@@ -0,0 +1,350 @@
+/**
+ * Auth Mutation Hooks
+ *
+ * TanStack Query mutation hooks for authentication-related write operations.
+ * These hooks handle user registration, login, token refresh, and Firebase authentication.
+ *
+ * @module api/mutations/auth
+ */
+
+import { useMutation, UseMutationOptions, UseMutationResult, useQueryClient } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import { userKeys } from '../queries/users';
+import type {
+  RegisterRequest,
+  LoginRequest,
+  RefreshTokenRequest,
+  FirebaseAuthRequest,
+  AuthResponse,
+  TokenResponse,
+} from '../types';
+
+// ============================================================================
+// MUTATION HOOKS
+// ============================================================================
+
+/**
+ * Register a new user account
+ *
+ * @description
+ * Creates a new user account with email/phone and password.
+ * Returns authentication tokens and user information upon successful registration.
+ *
+ * @endpoint POST /auth/register
+ *
+ * @example
+ * ```tsx
+ * import { useRegister } from '@growsober/sdk';
+ *
+ * function RegisterForm() {
+ *   const { mutate: register, isPending, error } = useRegister({
+ *     onSuccess: (data) => {
+ *       // Store tokens securely
+ *       await SecureStore.setItemAsync('accessToken', data.accessToken);
+ *       await SecureStore.setItemAsync('refreshToken', data.refreshToken);
+ *       navigation.navigate('Onboarding');
+ *     },
+ *     onError: (error) => {
+ *       Alert.alert('Registration failed', error.message);
+ *     },
+ *   });
+ *
+ *   const handleSubmit = () => {
+ *     register({
+ *       email: 'user@example.com',
+ *       password: 'SecurePassword123!',
+ *       name: 'John Doe',
+ *     });
+ *   };
+ *
+ *   return <Button onPress={handleSubmit} disabled={isPending} />;
+ * }
+ * ```
+ *
+ * @param options - TanStack Query mutation options
+ * @returns TanStack Query mutation result
+ */
+export function useRegister(
+  options?: Omit<UseMutationOptions<AuthResponse, Error, RegisterRequest>, 'mutationFn'>
+): UseMutationResult<AuthResponse, Error, RegisterRequest> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: RegisterRequest): Promise<AuthResponse> => {
+      const client = getApiClient();
+      const response = await client.post<AuthResponse>('/auth/register', data);
+      return response.data;
+    },
+    onSuccess: (data, variables, context) => {
+      // Invalidate current user query to trigger refetch with new token
+      queryClient.invalidateQueries({ queryKey: userKeys.me() });
+      // User's onSuccess is handled by spreading options
+    },
+    ...options,
+  });
+}
+
+/**
+ * Login with email/phone and password
+ *
+ * @description
+ * Authenticates an existing user with their credentials.
+ * Returns authentication tokens and user information upon successful login.
+ *
+ * @endpoint POST /auth/login
+ *
+ * @example
+ * ```tsx
+ * import { useLogin } from '@growsober/sdk';
+ *
+ * function LoginForm() {
+ *   const { mutate: login, isPending, error } = useLogin({
+ *     onSuccess: (data) => {
+ *       // Store tokens securely
+ *       await SecureStore.setItemAsync('accessToken', data.accessToken);
+ *       await SecureStore.setItemAsync('refreshToken', data.refreshToken);
+ *       navigation.navigate('Home');
+ *     },
+ *   });
+ *
+ *   const handleSubmit = () => {
+ *     login({
+ *       email: 'user@example.com',
+ *       password: 'SecurePassword123!',
+ *     });
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input type="email" name="email" />
+ *       <input type="password" name="password" />
+ *       <button type="submit" disabled={isPending}>
+ *         {isPending ? 'Logging in...' : 'Login'}
+ *       </button>
+ *       {error && <p className="error">{error.message}</p>}
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Login with phone number:
+ * ```tsx
+ * login({
+ *   phone: '+1234567890',
+ *   password: 'SecurePassword123!',
+ * });
+ * ```
+ *
+ * @param options - TanStack Query mutation options
+ * @returns TanStack Query mutation result
+ */
+export function useLogin(
+  options?: Omit<UseMutationOptions<AuthResponse, Error, LoginRequest>, 'mutationFn'>
+): UseMutationResult<AuthResponse, Error, LoginRequest> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: LoginRequest): Promise<AuthResponse> => {
+      const client = getApiClient();
+      const response = await client.post<AuthResponse>('/auth/login', data);
+      return response.data;
+    },
+    onSuccess: (data, variables, context) => {
+      // Invalidate current user query to trigger refetch with new token
+      queryClient.invalidateQueries({ queryKey: userKeys.me() });
+      // User's onSuccess is handled by spreading options
+    },
+    ...options,
+  });
+}
+
+/**
+ * Refresh access token using refresh token
+ *
+ * @description
+ * Obtains a new access token using a valid refresh token.
+ * Should be called when the access token expires.
+ *
+ * @endpoint POST /auth/refresh
+ *
+ * @example
+ * ```tsx
+ * import { useRefreshAuthToken } from '@growsober/sdk';
+ *
+ * function useTokenRefresh() {
+ *   const { mutateAsync: refreshToken } = useRefreshAuthToken();
+ *
+ *   const handleTokenExpired = async () => {
+ *     const storedRefreshToken = await SecureStore.getItemAsync('refreshToken');
+ *
+ *     if (!storedRefreshToken) {
+ *       navigation.navigate('Login');
+ *       return;
+ *     }
+ *
+ *     try {
+ *       const { accessToken, refreshToken: newRefreshToken } = await refreshToken({
+ *         refreshToken: storedRefreshToken,
+ *       });
+ *
+ *       // Store new tokens
+ *       await SecureStore.setItemAsync('accessToken', accessToken);
+ *       await SecureStore.setItemAsync('refreshToken', newRefreshToken);
+ *     } catch (error) {
+ *       // Refresh token is invalid or expired
+ *       navigation.navigate('Login');
+ *     }
+ *   };
+ *
+ *   return { handleTokenExpired };
+ * }
+ * ```
+ *
+ * @example
+ * Integrate with SDK configuration:
+ * ```tsx
+ * import { configureSDK } from '@growsober/sdk';
+ *
+ * configureSDK({
+ *   baseURL: 'https://api.growsober.app',
+ *   getAccessToken: async () => {
+ *     return await SecureStore.getItemAsync('accessToken');
+ *   },
+ *   refreshAccessToken: async () => {
+ *     const refreshToken = await SecureStore.getItemAsync('refreshToken');
+ *     const { accessToken, refreshToken: newRefreshToken } = await fetch('/auth/refresh', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ refreshToken }),
+ *     }).then(r => r.json());
+ *
+ *     await SecureStore.setItemAsync('accessToken', accessToken);
+ *     await SecureStore.setItemAsync('refreshToken', newRefreshToken);
+ *
+ *     return accessToken;
+ *   },
+ *   onUnauthorized: () => {
+ *     navigation.navigate('Login');
+ *   },
+ * });
+ * ```
+ *
+ * @param options - TanStack Query mutation options
+ * @returns TanStack Query mutation result
+ */
+export function useRefreshAuthToken(
+  options?: Omit<UseMutationOptions<TokenResponse, Error, RefreshTokenRequest>, 'mutationFn'>
+): UseMutationResult<TokenResponse, Error, RefreshTokenRequest> {
+  return useMutation({
+    mutationFn: async (data: RefreshTokenRequest): Promise<TokenResponse> => {
+      const client = getApiClient();
+      const response = await client.post<TokenResponse>('/auth/refresh', data);
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Authenticate with Firebase ID token
+ *
+ * @description
+ * Authenticates a user using a Firebase ID token.
+ * Creates a new user account if one doesn't exist, or logs in an existing user.
+ * Returns GrowSober authentication tokens and user information.
+ *
+ * @endpoint POST /auth/firebase
+ *
+ * @example
+ * ```tsx
+ * import { useFirebaseAuth } from '@growsober/sdk';
+ * import { signInWithPhoneNumber } from 'firebase/auth';
+ *
+ * function PhoneAuthScreen() {
+ *   const { mutate: firebaseAuth, isPending } = useFirebaseAuth({
+ *     onSuccess: (data) => {
+ *       // Store GrowSober tokens
+ *       await SecureStore.setItemAsync('accessToken', data.accessToken);
+ *       await SecureStore.setItemAsync('refreshToken', data.refreshToken);
+ *
+ *       if (data.user.onboardingCompleted) {
+ *         navigation.navigate('Home');
+ *       } else {
+ *         navigation.navigate('Onboarding');
+ *       }
+ *     },
+ *     onError: (error) => {
+ *       Alert.alert('Authentication failed', error.message);
+ *     },
+ *   });
+ *
+ *   const handlePhoneAuth = async (phoneNumber: string) => {
+ *     try {
+ *       // Firebase authentication flow
+ *       const confirmation = await signInWithPhoneNumber(auth, phoneNumber);
+ *       const code = await promptUserForCode(); // Your UI to get verification code
+ *       const credential = await confirmation.confirm(code);
+ *
+ *       // Get Firebase ID token
+ *       const idToken = await credential.user.getIdToken();
+ *
+ *       // Authenticate with GrowSober backend
+ *       firebaseAuth({ idToken });
+ *     } catch (error) {
+ *       console.error('Phone auth error:', error);
+ *     }
+ *   };
+ *
+ *   return <PhoneInput onSubmit={handlePhoneAuth} disabled={isPending} />;
+ * }
+ * ```
+ *
+ * @example
+ * With Google Sign-In:
+ * ```tsx
+ * import { GoogleSignin } from '@react-native-google-signin/google-signin';
+ *
+ * const handleGoogleSignIn = async () => {
+ *   const { idToken } = await GoogleSignin.signIn();
+ *   firebaseAuth({ idToken });
+ * };
+ * ```
+ *
+ * @example
+ * With Apple Sign-In:
+ * ```tsx
+ * import * as AppleAuthentication from 'expo-apple-authentication';
+ *
+ * const handleAppleSignIn = async () => {
+ *   const credential = await AppleAuthentication.signInAsync({
+ *     requestedScopes: [
+ *       AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
+ *       AppleAuthentication.AppleAuthenticationScope.EMAIL,
+ *     ],
+ *   });
+ *   firebaseAuth({ idToken: credential.identityToken });
+ * };
+ * ```
+ *
+ * @param options - TanStack Query mutation options
+ * @returns TanStack Query mutation result
+ */
+export function useFirebaseAuth(
+  options?: Omit<UseMutationOptions<AuthResponse, Error, FirebaseAuthRequest>, 'mutationFn'>
+): UseMutationResult<AuthResponse, Error, FirebaseAuthRequest> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: FirebaseAuthRequest): Promise<AuthResponse> => {
+      const client = getApiClient();
+      const response = await client.post<AuthResponse>('/auth/firebase', data);
+      return response.data;
+    },
+    onSuccess: (data, variables, context) => {
+      // Invalidate current user query to trigger refetch with new token
+      queryClient.invalidateQueries({ queryKey: userKeys.me() });
+      // User's onSuccess is handled by spreading options
+    },
+    ...options,
+  });
+}