@spotsdev/sdk 1.0.0

package/src/api/queries/misc.ts

@@ -0,0 +1,140 @@
+/**
+ * Misc Query Hooks
+ *
+ * TanStack Query hooks for cities, vibes, and other reference data.
+ * All types come from @prisma/client (via ../types re-export).
+ *
+ * API Response Patterns:
+ * - Reference data (vibes, templates, interests): { success, data: T[], timestamp }
+ * - Large datasets (cities, spots, posts): { success, data: { data: T[], meta }, timestamp }
+ */
+
+import { useQuery, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type { City, Vibe, LifeSituation, Interest, Intention, ApiResponse, PaginatedResponse } from '../types';
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+export const miscKeys = {
+  cities: () => ['cities'] as const,
+  vibes: () => ['vibes'] as const,
+  lifeSituations: () => ['life-situations'] as const,
+  interests: () => ['interests'] as const,
+  intentions: () => ['intentions'] as const,
+};
+
+// ============================================================================
+// QUERY HOOKS
+// ============================================================================
+
+/**
+ * Get all cities (paginated endpoint)
+ *
+ * @endpoint GET /api/v1/cities
+ * @returns PaginatedResponse with cities array
+ */
+export function useCities(
+  options?: Omit<UseQueryOptions<City[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<City[]> {
+  return useQuery({
+    queryKey: miscKeys.cities(),
+    queryFn: async (): Promise<City[]> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<PaginatedResponse<City>>>('/api/v1/cities');
+      // Cities endpoint returns paginated format: { data: { data: [], meta: {} } }
+      return response.data.data.data;
+    },
+    staleTime: 1000 * 60 * 60,
+    ...options,
+  });
+}
+
+/**
+ * Get all vibes (flat array - reference data)
+ *
+ * @endpoint GET /api/v1/vibes
+ * @returns Flat array of vibes (not paginated)
+ */
+export function useVibes(
+  options?: Omit<UseQueryOptions<Vibe[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Vibe[]> {
+  return useQuery({
+    queryKey: miscKeys.vibes(),
+    queryFn: async (): Promise<Vibe[]> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<Vibe[]>>('/api/v1/vibes');
+      // Vibes endpoint returns flat array: { data: [] }
+      return response.data.data;
+    },
+    staleTime: 1000 * 60 * 60,
+    ...options,
+  });
+}
+
+/**
+ * Get all life situations (flat array - reference data for onboarding)
+ *
+ * @endpoint GET /api/v1/life-situations
+ * @returns Flat array of life situations (not paginated)
+ */
+export function useLifeSituations(
+  options?: Omit<UseQueryOptions<LifeSituation[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<LifeSituation[]> {
+  return useQuery({
+    queryKey: miscKeys.lifeSituations(),
+    queryFn: async (): Promise<LifeSituation[]> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<LifeSituation[]>>('/api/v1/life-situations');
+      // Life situations endpoint returns flat array: { data: [] }
+      return response.data.data;
+    },
+    staleTime: 1000 * 60 * 60,
+    ...options,
+  });
+}
+
+/**
+ * Get all interests (flat array - reference data)
+ *
+ * @endpoint GET /api/v1/interests
+ * @returns Flat array of interests (not paginated)
+ */
+export function useInterests(
+  options?: Omit<UseQueryOptions<Interest[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Interest[]> {
+  return useQuery({
+    queryKey: miscKeys.interests(),
+    queryFn: async (): Promise<Interest[]> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<Interest[]>>('/api/v1/interests');
+      // Interests endpoint returns flat array: { data: [] }
+      return response.data.data;
+    },
+    staleTime: 1000 * 60 * 60,
+    ...options,
+  });
+}
+
+/**
+ * Get all intentions (flat array - reference data)
+ *
+ * @endpoint GET /api/v1/intentions
+ * @returns Flat array of intentions (not paginated)
+ */
+export function useIntentions(
+  options?: Omit<UseQueryOptions<Intention[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Intention[]> {
+  return useQuery({
+    queryKey: miscKeys.intentions(),
+    queryFn: async (): Promise<Intention[]> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<Intention[]>>('/api/v1/intentions');
+      // Intentions endpoint returns flat array: { data: [] }
+      return response.data.data;
+    },
+    staleTime: 1000 * 60 * 60,
+    ...options,
+  });
+}

package/src/api/queries/notifications.ts

@@ -0,0 +1,66 @@
+/**
+ * Notifications Query Hooks
+ *
+ * TanStack Query hooks for notification operations.
+ */
+
+import { useQuery, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type { Notification, ApiResponse } from '../types';
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+export const notificationKeys = {
+  all: ['notifications'] as const,
+  lists: () => [...notificationKeys.all, 'list'] as const,
+  list: (params?: { limit?: number; unreadOnly?: boolean }) => [...notificationKeys.lists(), params] as const,
+  unreadCount: () => [...notificationKeys.all, 'unreadCount'] as const,
+};
+
+// ============================================================================
+// QUERY HOOKS
+// ============================================================================
+
+/**
+ * Get notifications for current user
+ *
+ * @endpoint GET /api/v1/notifications
+ */
+export function useNotifications(
+  params?: { limit?: number; unreadOnly?: boolean },
+  options?: Omit<UseQueryOptions<Notification[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Notification[]> {
+  return useQuery({
+    queryKey: notificationKeys.list(params),
+    queryFn: async (): Promise<Notification[]> => {
+      const client = getApiClient();
+      const queryParams = new URLSearchParams();
+      if (params?.limit) queryParams.set('limit', String(params.limit));
+      if (params?.unreadOnly) queryParams.set('unreadOnly', String(params.unreadOnly));
+      const response = await client.get<ApiResponse<Notification[]>>(`/api/v1/notifications?${queryParams}`);
+      return response.data.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get unread notification count
+ *
+ * @endpoint GET /api/v1/notifications/unread-count
+ */
+export function useUnreadNotificationCount(
+  options?: Omit<UseQueryOptions<number>, 'queryKey' | 'queryFn'>
+): UseQueryResult<number> {
+  return useQuery({
+    queryKey: notificationKeys.unreadCount(),
+    queryFn: async (): Promise<number> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<{ count: number }>>('/api/v1/notifications/unread-count');
+      return response.data.data.count;
+    },
+    ...options,
+  });
+}

package/src/api/queries/orders.ts

@@ -0,0 +1,119 @@
+/**
+ * Orders Query Hooks
+ *
+ * TanStack Query hooks for order-related operations.
+ */
+
+import { useQuery, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type { Order, OrderItem, Product, Spot, OrderStatus, ApiResponse, PaginatedResponse } from '../types';
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+export const orderKeys = {
+  all: ['orders'] as const,
+  lists: () => [...orderKeys.all, 'list'] as const,
+  list: (filters?: Record<string, unknown>) => [...orderKeys.lists(), filters] as const,
+  details: () => [...orderKeys.all, 'detail'] as const,
+  detail: (id: string) => [...orderKeys.details(), id] as const,
+  myOrders: () => [...orderKeys.all, 'my'] as const,
+  spotOrders: (spotId: string) => [...orderKeys.all, 'spot', spotId] as const,
+};
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface OrderWithDetails extends Order {
+  items: (OrderItem & {
+    product: Pick<Product, 'id' | 'name' | 'slug' | 'type' | 'imageUrl'>;
+  })[];
+  spot: Pick<Spot, 'id' | 'name' | 'slug'>;
+}
+
+export interface OrderFilters {
+  status?: OrderStatus;
+  limit?: number;
+  page?: number;
+}
+
+// ============================================================================
+// QUERY HOOKS
+// ============================================================================
+
+/**
+ * Get current user's orders (purchases)
+ *
+ * @endpoint GET /api/v1/users/me/orders
+ */
+export function useMyOrders(
+  params?: OrderFilters,
+  options?: Omit<UseQueryOptions<PaginatedResponse<OrderWithDetails>>, 'queryKey' | 'queryFn'>
+): UseQueryResult<PaginatedResponse<OrderWithDetails>> {
+  return useQuery({
+    queryKey: orderKeys.list({ ...params, my: true }),
+    queryFn: async (): Promise<PaginatedResponse<OrderWithDetails>> => {
+      const client = getApiClient();
+      const queryParams = new URLSearchParams();
+      if (params?.status) queryParams.set('status', params.status);
+      if (params?.limit) queryParams.set('limit', String(params.limit));
+      if (params?.page) queryParams.set('page', String(params.page));
+      const response = await client.get<ApiResponse<PaginatedResponse<OrderWithDetails>>>(
+        `/api/v1/users/me/orders?${queryParams}`
+      );
+      return response.data.data;
+    },
+    ...options,
+  });
+}
+
+/**
+ * Get a single order by ID
+ *
+ * @endpoint GET /api/v1/orders/{orderId}
+ */
+export function useOrder(
+  orderId: string,
+  options?: Omit<UseQueryOptions<OrderWithDetails>, 'queryKey' | 'queryFn'>
+): UseQueryResult<OrderWithDetails> {
+  return useQuery({
+    queryKey: orderKeys.detail(orderId),
+    queryFn: async (): Promise<OrderWithDetails> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<OrderWithDetails>>(`/api/v1/orders/${orderId}`);
+      return response.data.data;
+    },
+    enabled: !!orderId,
+    ...options,
+  });
+}
+
+/**
+ * Get orders for a spot (seller view)
+ *
+ * @endpoint GET /api/v1/seller/spots/{spotId}/orders
+ */
+export function useSpotOrders(
+  spotId: string,
+  params?: OrderFilters,
+  options?: Omit<UseQueryOptions<PaginatedResponse<OrderWithDetails>>, 'queryKey' | 'queryFn'>
+): UseQueryResult<PaginatedResponse<OrderWithDetails>> {
+  return useQuery({
+    queryKey: orderKeys.spotOrders(spotId),
+    queryFn: async (): Promise<PaginatedResponse<OrderWithDetails>> => {
+      const client = getApiClient();
+      const queryParams = new URLSearchParams();
+      if (params?.status) queryParams.set('status', params.status);
+      if (params?.limit) queryParams.set('limit', String(params.limit));
+      if (params?.page) queryParams.set('page', String(params.page));
+      const response = await client.get<ApiResponse<PaginatedResponse<OrderWithDetails>>>(
+        `/api/v1/seller/spots/${spotId}/orders?${queryParams}`
+      );
+      return response.data.data;
+    },
+    enabled: !!spotId,
+    ...options,
+  });
+}

package/src/api/queries/posts.ts

@@ -0,0 +1,142 @@
+/**
+ * Posts Query Hooks
+ *
+ * TanStack Query hooks for post/board operations.
+ */
+
+import { useQuery, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type { Post, PostResponse, ApiResponse, PostStatusDto } from '../types';
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+export const postKeys = {
+  all: ['posts'] as const,
+  lists: () => [...postKeys.all, 'list'] as const,
+  list: (filters?: Record<string, unknown>) => [...postKeys.lists(), filters] as const,
+  bySpot: (spotId: string, filters?: Record<string, unknown>) => [...postKeys.all, 'spot', spotId, filters] as const,
+  details: () => [...postKeys.all, 'detail'] as const,
+  detail: (id: string) => [...postKeys.details(), id] as const,
+  responses: (postId: string) => [...postKeys.detail(postId), 'responses'] as const,
+  status: (postId: string) => [...postKeys.detail(postId), 'status'] as const,
+};
+
+// ============================================================================
+// QUERY HOOKS
+// ============================================================================
+
+/**
+ * Get posts for a spot
+ *
+ * @endpoint GET /api/v1/spots/{spotId}/posts
+ */
+export function useSpotPosts(
+  spotId: string,
+  params?: { postType?: string; status?: string; page?: number; limit?: number },
+  options?: Omit<UseQueryOptions<Post[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Post[]> {
+  return useQuery({
+    queryKey: postKeys.bySpot(spotId, params),
+    queryFn: async (): Promise<Post[]> => {
+      const client = getApiClient();
+      const queryParams = new URLSearchParams();
+      if (params?.postType) queryParams.set('postType', params.postType);
+      if (params?.status) queryParams.set('status', params.status);
+      if (params?.page) queryParams.set('page', String(params.page));
+      if (params?.limit) queryParams.set('limit', String(params.limit));
+      const response = await client.get<ApiResponse<Post[]>>(`/api/v1/spots/${spotId}/posts?${queryParams}`);
+      return response.data.data;
+    },
+    enabled: !!spotId,
+    ...options,
+  });
+}
+
+/**
+ * Get a single post by ID
+ *
+ * @endpoint GET /api/v1/posts/{postId}
+ */
+export function usePost(
+  postId: string,
+  options?: Omit<UseQueryOptions<Post>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Post> {
+  return useQuery({
+    queryKey: postKeys.detail(postId),
+    queryFn: async (): Promise<Post> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<Post>>(`/api/v1/posts/${postId}`);
+      return response.data.data;
+    },
+    enabled: !!postId,
+    ...options,
+  });
+}
+
+/**
+ * Get responses for a post
+ *
+ * @endpoint GET /api/v1/posts/{postId}/responses
+ */
+export function usePostResponses(
+  postId: string,
+  options?: Omit<UseQueryOptions<PostResponse[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<PostResponse[]> {
+  return useQuery({
+    queryKey: postKeys.responses(postId),
+    queryFn: async (): Promise<PostResponse[]> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<PostResponse[]>>(`/api/v1/posts/${postId}/responses`);
+      return response.data.data;
+    },
+    enabled: !!postId,
+    ...options,
+  });
+}
+
+/**
+ * Get all posts (with filters)
+ *
+ * @endpoint GET /api/v1/posts
+ */
+export function usePosts(
+  params?: { postType?: string; limit?: number },
+  options?: Omit<UseQueryOptions<Post[]>, 'queryKey' | 'queryFn'>
+): UseQueryResult<Post[]> {
+  return useQuery({
+    queryKey: postKeys.list(params),
+    queryFn: async (): Promise<Post[]> => {
+      const client = getApiClient();
+      const queryParams = new URLSearchParams();
+      if (params?.postType) queryParams.set('postType', params.postType);
+      if (params?.limit) queryParams.set('limit', String(params.limit));
+      const response = await client.get<ApiResponse<Post[]>>(`/api/v1/posts?${queryParams}`);
+      return response.data.data;
+    },
+    ...options,
+  });
+}
+
+
+/**
+ * Get user's status for a post (read/hidden/pinned)
+ *
+ * @endpoint GET /api/v1/posts/{postId}/status
+ */
+export function usePostStatus(
+  postId: string,
+  options?: Omit<UseQueryOptions<PostStatusDto>, 'queryKey' | 'queryFn'>
+): UseQueryResult<PostStatusDto> {
+  return useQuery({
+    queryKey: postKeys.status(postId),
+    queryFn: async (): Promise<PostStatusDto> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<PostStatusDto>>(`/api/v1/posts/${postId}/status`);
+      return response.data.data;
+    },
+    enabled: !!postId,
+    ...options,
+  });
+}

package/src/api/queries/products.ts

@@ -0,0 +1,123 @@
+/**
+ * Products Query Hooks
+ *
+ * TanStack Query hooks for product-related operations.
+ */
+
+import { useQuery, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import { getApiClient } from '../client';
+import type { Product, ApiResponse, PaginatedResponse, ProductType, ProductStatus } from '../types';
+
+// ============================================================================
+// QUERY KEYS
+// ============================================================================
+
+export const productKeys = {
+  all: ['products'] as const,
+  lists: () => [...productKeys.all, 'list'] as const,
+  list: (filters?: Record<string, unknown>) => [...productKeys.lists(), filters] as const,
+  details: () => [...productKeys.all, 'detail'] as const,
+  detail: (id: string) => [...productKeys.details(), id] as const,
+  bySlug: (spotId: string, slug: string) => [...productKeys.all, 'slug', spotId, slug] as const,
+  bySpot: (spotId: string) => [...productKeys.all, 'spot', spotId] as const,
+};
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface ProductFilters {
+  spotId?: string;
+  type?: ProductType;
+  status?: ProductStatus;
+  limit?: number;
+  page?: number;
+}
+
+export interface ProductWithSpot extends Product {
+  spot: {
+    id: string;
+    name: string;
+    slug: string;
+  };
+}
+
+// ============================================================================
+// QUERY HOOKS
+// ============================================================================
+
+/**
+ * Get products for a spot (public browse)
+ *
+ * @endpoint GET /api/v1/spots/{spotId}/products
+ */
+export function useSpotProducts(
+  spotId: string,
+  params?: { type?: ProductType; limit?: number; page?: number },
+  options?: Omit<UseQueryOptions<PaginatedResponse<Product>>, 'queryKey' | 'queryFn'>
+): UseQueryResult<PaginatedResponse<Product>> {
+  return useQuery({
+    queryKey: productKeys.bySpot(spotId),
+    queryFn: async (): Promise<PaginatedResponse<Product>> => {
+      const client = getApiClient();
+      const queryParams = new URLSearchParams();
+      if (params?.limit) queryParams.set('limit', String(params.limit));
+      if (params?.page) queryParams.set('page', String(params.page));
+      if (params?.type) queryParams.set('type', params.type);
+      const response = await client.get<ApiResponse<PaginatedResponse<Product>>>(
+        `/api/v1/spots/${spotId}/products?${queryParams}`
+      );
+      return response.data.data;
+    },
+    enabled: !!spotId,
+    ...options,
+  });
+}
+
+/**
+ * Get a product by ID
+ *
+ * @endpoint GET /api/v1/products/{productId}
+ */
+export function useProduct(
+  productId: string,
+  options?: Omit<UseQueryOptions<ProductWithSpot>, 'queryKey' | 'queryFn'>
+): UseQueryResult<ProductWithSpot> {
+  return useQuery({
+    queryKey: productKeys.detail(productId),
+    queryFn: async (): Promise<ProductWithSpot> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<ProductWithSpot>>(`/api/v1/products/${productId}`);
+      return response.data.data;
+    },
+    enabled: !!productId,
+    ...options,
+  });
+}
+
+/**
+ * Get a product by slug (within a spot)
+ *
+ * @endpoint GET /api/v1/spots/{spotId}/products/slug/{slug}
+ */
+export function useProductBySlug(
+  spotId: string,
+  slug: string,
+  options?: Omit<UseQueryOptions<ProductWithSpot>, 'queryKey' | 'queryFn'>
+): UseQueryResult<ProductWithSpot> {
+  return useQuery({
+    queryKey: productKeys.bySlug(spotId, slug),
+    queryFn: async (): Promise<ProductWithSpot> => {
+      const client = getApiClient();
+      const response = await client.get<ApiResponse<ProductWithSpot>>(
+        `/api/v1/spots/${spotId}/products/slug/${slug}`
+      );
+      return response.data.data;
+    },
+    enabled: !!spotId && !!slug,
+    ...options,
+  });
+}
+
+// Note: To list products as a seller, use useSpotProducts with your spot ID.
+// There is no cross-spot product listing endpoint currently.