@spotsdev/sdk 1.0.0

package/src/api/mutations/spots.ts

@@ -0,0 +1,146 @@
+/**
+ * Spots Mutation Hooks
+ *
+ * TanStack Query hooks for spot mutation operations.
+ */
+
+import { useMutation, useQueryClient, UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import { spotKeys } from '../queries/spots';
+import { userKeys } from '../queries/users';
+import type { Spot, ClaimSpotRequest, ApiResponse } from '../types';
+
+// ============================================================================
+// MUTATION HOOKS
+// ============================================================================
+
+/**
+ * Create a new spot
+ *
+ * @endpoint POST /api/v1/spots
+ */
+export function useCreateSpot(
+  options?: Omit<UseMutationOptions<Spot, Error, Partial<Spot>>, 'mutationFn'>
+): UseMutationResult<Spot, Error, Partial<Spot>> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: Partial<Spot>): Promise<Spot> => {
+      const client = getApiClient();
+      const response = await client.post<ApiResponse<Spot>>('/api/v1/spots', data);
+      return response.data.data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: spotKeys.lists() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Update a spot
+ *
+ * @endpoint PUT /api/v1/spots/{spotId}
+ */
+export function useUpdateSpot(
+  options?: Omit<UseMutationOptions<Spot, Error, { spotId: string } & Partial<Spot>>, 'mutationFn'>
+): UseMutationResult<Spot, Error, { spotId: string } & Partial<Spot>> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({ spotId, ...data }): Promise<Spot> => {
+      const client = getApiClient();
+      const response = await client.put<ApiResponse<Spot>>(`/api/v1/spots/${spotId}`, data);
+      return response.data.data;
+    },
+    onSuccess: (data, variables) => {
+      queryClient.setQueryData(spotKeys.detail(variables.spotId), data);
+    },
+    ...options,
+  });
+}
+
+/**
+ * Claim a spot (for business owners)
+ *
+ * @endpoint POST /api/v1/spots/{spotId}/claim
+ */
+export function useClaimSpot(
+  options?: Omit<UseMutationOptions<{ claimId: string }, Error, { spotId: string } & ClaimSpotRequest>, 'mutationFn'>
+): UseMutationResult<{ claimId: string }, Error, { spotId: string } & ClaimSpotRequest> {
+  return useMutation({
+    mutationFn: async ({ spotId, ...data }): Promise<{ claimId: string }> => {
+      const client = getApiClient();
+      const response = await client.post<ApiResponse<{ claimId: string }>>(`/api/v1/spots/${spotId}/claim`, data);
+      return response.data.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Subscribe to a spot
+ *
+ * @endpoint POST /api/v1/spots/{spotId}/subscribe
+ */
+export function useSubscribeToSpot(
+  options?: Omit<UseMutationOptions<void, Error, string>, 'mutationFn'>
+): UseMutationResult<void, Error, string> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (spotId: string): Promise<void> => {
+      const client = getApiClient();
+      await client.post(`/api/v1/spots/${spotId}/subscribe`);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.subscriptions() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Unsubscribe from a spot
+ *
+ * @endpoint DELETE /api/v1/spots/{spotId}/subscribe
+ */
+export function useUnsubscribeFromSpot(
+  options?: Omit<UseMutationOptions<void, Error, string>, 'mutationFn'>
+): UseMutationResult<void, Error, string> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (spotId: string): Promise<void> => {
+      const client = getApiClient();
+      await client.delete(`/api/v1/spots/${spotId}/subscribe`);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.subscriptions() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Toggle favorite status on a spot
+ *
+ * @endpoint POST /api/v1/spots/{spotId}/favorite
+ */
+export function useFavoriteSpot(
+  options?: Omit<UseMutationOptions<{ isFavorite: boolean }, Error, string>, 'mutationFn'>
+): UseMutationResult<{ isFavorite: boolean }, Error, string> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (spotId: string): Promise<{ isFavorite: boolean }> => {
+      const client = getApiClient();
+      const response = await client.post<ApiResponse<{ isFavorite: boolean }>>(`/api/v1/spots/${spotId}/favorite`);
+      return response.data.data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.favorites() });
+    },
+    ...options,
+  });
+}

package/src/api/mutations/users.ts

@@ -0,0 +1,197 @@
+/**
+ * Users Mutation Hooks
+ *
+ * TanStack Query hooks for user mutation operations.
+ */
+
+import { useMutation, useQueryClient, UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import { userKeys } from '../queries/users';
+import type { User, UpdateProfileRequest, ApiResponse } from '../types';
+
+// ============================================================================
+// MUTATION HOOKS
+// ============================================================================
+
+/**
+ * Update current user's profile
+ *
+ * @endpoint PUT /api/v1/users/me
+ */
+export function useUpdateProfile(
+  options?: Omit<UseMutationOptions<User, Error, UpdateProfileRequest>, 'mutationFn'>
+): UseMutationResult<User, Error, UpdateProfileRequest> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: UpdateProfileRequest): Promise<User> => {
+      const client = getApiClient();
+      const response = await client.put<ApiResponse<User>>('/api/v1/users/me', data);
+      return response.data.data;
+    },
+    onSuccess: (data) => {
+      queryClient.setQueryData(userKeys.me(), data);
+    },
+    ...options,
+  });
+}
+
+/**
+ * Upload avatar
+ *
+ * @endpoint POST /api/v1/users/me/avatar
+ */
+export function useUploadAvatar(
+  options?: Omit<UseMutationOptions<{ avatarUrl: string }, Error, FormData>, 'mutationFn'>
+): UseMutationResult<{ avatarUrl: string }, Error, FormData> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (formData: FormData): Promise<{ avatarUrl: string }> => {
+      const client = getApiClient();
+      const response = await client.post<ApiResponse<{ avatarUrl: string }>>('/api/v1/users/me/avatar', formData, {
+        headers: { 'Content-Type': 'multipart/form-data' },
+      });
+      return response.data.data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.me() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Delete current user's account
+ *
+ * @endpoint DELETE /api/v1/users/me
+ */
+export function useDeleteAccount(
+  options?: Omit<UseMutationOptions<void, Error, void>, 'mutationFn'>
+): UseMutationResult<void, Error, void> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (): Promise<void> => {
+      const client = getApiClient();
+      await client.delete('/api/v1/users/me');
+    },
+    onSuccess: () => {
+      queryClient.clear();
+    },
+    ...options,
+  });
+}
+
+/**
+ * Update user vibes
+ *
+ * @endpoint PUT /api/v1/user/me/vibes
+ */
+export function useUpdateVibes(
+  options?: Omit<UseMutationOptions<User, Error, { vibes: string[] }>, 'mutationFn'>
+): UseMutationResult<User, Error, { vibes: string[] }> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: { vibes: string[] }): Promise<User> => {
+      const client = getApiClient();
+      const response = await client.put<ApiResponse<User>>('/api/v1/user/me/vibes', data);
+      return response.data.data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.me() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Update user interests
+ *
+ * @endpoint PUT /api/v1/user/me/interests
+ */
+export function useUpdateInterests(
+  options?: Omit<UseMutationOptions<User, Error, { interests: string[] }>, 'mutationFn'>
+): UseMutationResult<User, Error, { interests: string[] }> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: { interests: string[] }): Promise<User> => {
+      const client = getApiClient();
+      const response = await client.put<ApiResponse<User>>('/api/v1/user/me/interests', data);
+      return response.data.data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.me() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Complete onboarding step
+ *
+ * @endpoint POST /api/v1/user/me/onboarding-step
+ */
+export function useCompleteOnboardingStep(
+  options?: Omit<UseMutationOptions<User, Error, { step: number }>, 'mutationFn'>
+): UseMutationResult<User, Error, { step: number }> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: { step: number }): Promise<User> => {
+      const client = getApiClient();
+      const response = await client.post<ApiResponse<User>>('/api/v1/user/me/onboarding-step', data);
+      return response.data.data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.me() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Block a user
+ *
+ * @endpoint POST /api/v1/users/{id}/block
+ */
+export function useBlockUser(
+  options?: Omit<UseMutationOptions<void, Error, string>, 'mutationFn'>
+): UseMutationResult<void, Error, string> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (userId: string): Promise<void> => {
+      const client = getApiClient();
+      await client.post(`/api/v1/users/${userId}/block`);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.blocked() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Unblock a user
+ *
+ * @endpoint DELETE /api/v1/users/{id}/block
+ */
+export function useUnblockUser(
+  options?: Omit<UseMutationOptions<void, Error, string>, 'mutationFn'>
+): UseMutationResult<void, Error, string> {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (userId: string): Promise<void> => {
+      const client = getApiClient();
+      await client.delete(`/api/v1/users/${userId}/block`);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.blocked() });
+    },
+    ...options,
+  });
+}

package/src/api/queries/auth.ts

@@ -0,0 +1,67 @@
+/**
+ * Auth Mutation Hooks
+ *
+ * TanStack Query hooks for authentication operations.
+ */
+
+import { useMutation, UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type { SendOtpRequest, VerifyOtpRequest, AuthResponse, ApiResponse } from '../types';
+
+// ============================================================================
+// MUTATION HOOKS
+// ============================================================================
+
+/**
+ * Send OTP to phone number
+ *
+ * @endpoint POST /api/v1/auth/send-otp
+ */
+export function useSendOtp(
+  options?: Omit<UseMutationOptions<ApiResponse<{ sent: boolean }>, Error, SendOtpRequest>, 'mutationFn'>
+): UseMutationResult<ApiResponse<{ sent: boolean }>, Error, SendOtpRequest> {
+  return useMutation({
+    mutationFn: async (data: SendOtpRequest) => {
+      const client = getApiClient();
+      const response = await client.post<ApiResponse<{ sent: boolean }>>('/api/v1/auth/send-otp', data);
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Verify OTP and authenticate
+ *
+ * @endpoint POST /api/v1/auth/verify-otp
+ */
+export function useVerifyOtp(
+  options?: Omit<UseMutationOptions<AuthResponse, Error, VerifyOtpRequest>, 'mutationFn'>
+): UseMutationResult<AuthResponse, Error, VerifyOtpRequest> {
+  return useMutation({
+    mutationFn: async (data: VerifyOtpRequest) => {
+      const client = getApiClient();
+      const response = await client.post<AuthResponse>('/api/v1/auth/verify-otp', data);
+      return response.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Refresh access token
+ *
+ * @endpoint POST /api/v1/auth/refresh
+ */
+export function useRefreshToken(
+  options?: Omit<UseMutationOptions<{ accessToken: string }, Error, { refreshToken: string }>, 'mutationFn'>
+): UseMutationResult<{ accessToken: string }, Error, { refreshToken: string }> {
+  return useMutation({
+    mutationFn: async (data: { refreshToken: string }) => {
+      const client = getApiClient();
+      const response = await client.post<{ accessToken: string }>('/api/v1/auth/refresh', data);
+      return response.data;
+    },
+    ...options,
+  });
+}

package/src/api/queries/clubs.ts

@@ -0,0 +1,135 @@
+/**
+ * Clubs Query Hooks
+ *
+ * TanStack Query hooks for club operations.
+ */
+
+import { useQuery, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type { Club, ApiResponse } from '../types';
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+export const clubKeys = {
+  all: ['clubs'] as const,
+  bySpot: (spotId: string) => [...clubKeys.all, 'spot', spotId] as const,
+  details: () => [...clubKeys.all, 'detail'] as const,
+  detail: (id: string) => [...clubKeys.details(), id] as const,
+  bySlug: (slug: string) => [...clubKeys.all, 'slug', slug] as const,
+  byUser: (userId: string) => [...clubKeys.all, 'user', userId] as const,
+  membership: (clubId: string, userId: string) => [...clubKeys.detail(clubId), 'membership', userId] as const,
+};
+
+// ============================================================================
+// QUERY HOOKS
+// ============================================================================
+
+/**
+ * Get clubs for a spot
+ *
+ * @endpoint GET /api/v1/clubs/spot/{spotId}
+ */
+export function useClubsBySpot(
+  spotId: string,
+  options?: Omit<UseQueryOptions<Club[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Club[]> {
+  return useQuery({
+    queryKey: clubKeys.bySpot(spotId),
+    queryFn: async (): Promise<Club[]> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<Club[]>>(`/api/v1/clubs/spot/${spotId}`);
+      return response.data.data;
+    },
+    enabled: !!spotId,
+    ...options,
+  });
+}
+
+/**
+ * Get a club by ID
+ *
+ * @endpoint GET /api/v1/clubs/{id}
+ */
+export function useClub(
+  clubId: string,
+  options?: Omit<UseQueryOptions<Club>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Club> {
+  return useQuery({
+    queryKey: clubKeys.detail(clubId),
+    queryFn: async (): Promise<Club> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<Club>>(`/api/v1/clubs/${clubId}`);
+      return response.data.data;
+    },
+    enabled: !!clubId,
+    ...options,
+  });
+}
+
+/**
+ * Get a club by slug
+ *
+ * @endpoint GET /api/v1/clubs/slug/{slug}
+ */
+export function useClubBySlug(
+  slug: string,
+  options?: Omit<UseQueryOptions<Club>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Club> {
+  return useQuery({
+    queryKey: clubKeys.bySlug(slug),
+    queryFn: async (): Promise<Club> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<Club>>(`/api/v1/clubs/slug/${slug}`);
+      return response.data.data;
+    },
+    enabled: !!slug,
+    ...options,
+  });
+}
+
+/**
+ * Get clubs for a user
+ *
+ * @endpoint GET /api/v1/clubs/user/{userId}
+ */
+export function useClubsByUser(
+  userId: string,
+  options?: Omit<UseQueryOptions<Club[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Club[]> {
+  return useQuery({
+    queryKey: clubKeys.byUser(userId),
+    queryFn: async (): Promise<Club[]> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<Club[]>>(`/api/v1/clubs/user/${userId}`);
+      return response.data.data;
+    },
+    enabled: !!userId,
+    ...options,
+  });
+}
+
+/**
+ * Get membership status for a user in a club
+ *
+ * @endpoint GET /api/v1/clubs/{id}/membership/{userId}
+ */
+export function useClubMembership(
+  clubId: string,
+  userId: string,
+  options?: Omit<UseQueryOptions<{ isMember: boolean; role?: string }>, 'queryKey' | 'queryFn'>
+): UseQueryResult<{ isMember: boolean; role?: string }> {
+  return useQuery({
+    queryKey: clubKeys.membership(clubId, userId),
+    queryFn: async () => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<{ isMember: boolean; role?: string }>>(
+        `/api/v1/clubs/${clubId}/membership/${userId}`
+      );
+      return response.data.data;
+    },
+    enabled: !!clubId && !!userId,
+    ...options,
+  });
+}

package/src/api/queries/conversations.ts

@@ -0,0 +1,94 @@
+/**
+ * Conversations Query Hooks
+ *
+ * TanStack Query hooks for conversation/messaging operations.
+ */
+
+import { useQuery, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type { Conversation, Message, ApiResponse } from '../types';
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+export const conversationKeys = {
+  all: ['conversations'] as const,
+  lists: () => [...conversationKeys.all, 'list'] as const,
+  list: () => [...conversationKeys.lists()] as const,
+  details: () => [...conversationKeys.all, 'detail'] as const,
+  detail: (id: string) => [...conversationKeys.details(), id] as const,
+  messages: (conversationId: string, params?: { before?: string }) =>
+    [...conversationKeys.detail(conversationId), 'messages', params] as const,
+};
+
+// ============================================================================
+// QUERY HOOKS
+// ============================================================================
+
+/**
+ * Get all conversations for current user
+ *
+ * @endpoint GET /api/v1/conversations
+ */
+export function useConversations(
+  options?: Omit<UseQueryOptions<Conversation[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Conversation[]> {
+  return useQuery({
+    queryKey: conversationKeys.list(),
+    queryFn: async (): Promise<Conversation[]> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<Conversation[]>>('/api/v1/conversations');
+      return response.data.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get a single conversation with details
+ *
+ * @endpoint GET /api/v1/conversations/{id}
+ */
+export function useConversation(
+  conversationId: string,
+  options?: Omit<UseQueryOptions<Conversation>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Conversation> {
+  return useQuery({
+    queryKey: conversationKeys.detail(conversationId),
+    queryFn: async (): Promise<Conversation> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<Conversation>>(`/api/v1/conversations/${conversationId}`);
+      return response.data.data;
+    },
+    enabled: !!conversationId,
+    ...options,
+  });
+}
+
+/**
+ * Get messages for a conversation
+ *
+ * @endpoint GET /api/v1/conversations/{id}/messages
+ */
+export function useConversationMessages(
+  conversationId: string,
+  params?: { limit?: number; before?: string },
+  options?: Omit<UseQueryOptions<{ data: Message[]; meta: { hasMore: boolean; oldestMessageAt: string | null } }>, 'queryKey' | 'queryFn'>
+): UseQueryResult<{ data: Message[]; meta: { hasMore: boolean; oldestMessageAt: string | null } }> {
+  return useQuery({
+    queryKey: conversationKeys.messages(conversationId, params),
+    queryFn: async () => {
+      const client = getApiClient();
+      const queryParams = new URLSearchParams();
+      if (params?.limit) queryParams.set('limit', String(params.limit));
+      if (params?.before) queryParams.set('before', params.before);
+      const response = await client.get<{ data: Message[]; meta: { hasMore: boolean; oldestMessageAt: string | null } }>(
+        `/api/v1/conversations/${conversationId}/messages?${queryParams}`
+      );
+      return response.data;
+    },
+    enabled: !!conversationId,
+    ...options,
+  });
+}

package/src/api/queries/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Spots SDK Query Hooks Index
+ *
+ * Re-exports all query hooks and keys.
+ */
+
+// Auth (mutations, but grouped with queries for convenience)
+export * from './auth';
+
+// Users
+export * from './users';
+export { userKeys } from './users';
+
+// Spots
+export * from './spots';
+export { spotKeys } from './spots';
+
+// Posts
+export * from './posts';
+export { postKeys } from './posts';
+
+// Conversations
+export * from './conversations';
+export { conversationKeys } from './conversations';
+
+// Clubs
+export * from './clubs';
+export { clubKeys } from './clubs';
+
+// Templates
+export * from './templates';
+export { templateKeys } from './templates';
+
+// Notifications
+export * from './notifications';
+export { notificationKeys } from './notifications';
+
+// Misc (cities, vibes, events)
+export * from './misc';
+export { miscKeys } from './misc';
+
+// Products (marketplace)
+export * from './products';
+export { productKeys } from './products';
+
+// Orders (marketplace)
+export * from './orders';
+export { orderKeys } from './orders';