@kasuvia/sdk 0.0.8 → 0.0.9

package/src/services/review.service.ts

@@ -0,0 +1,211 @@
+/**
+ * Review and Comment Service
+ *
+ * Handles review and comment operations using REST API.
+ * Stateless - all configuration passed as parameters.
+ *
+ * REAL BUG FIXED (2026-09-21): every URL here hardcoded a literal `/api/v1`
+ * prefix AND used a completely different path shape than the real
+ * kasuvia-crm-go backend (`kasuvia-crm-go/internal/api/v1/endpoints/
+ * reviews.go` + `admin_reviews.go`) — e.g. `POST /api/v1/reviews/comments`
+ * vs the real `POST /api/v1/comments`, `GET /api/v1/reviews/products/{id}`
+ * vs the real `GET /api/v1/products/{id}/reviews`. Every function 404'd.
+ * `config.backendUrls.crm` already includes `/api/v1` (same convention as
+ * every other backendUrls.* entry — see payment.service.ts/order.service.ts)
+ * so the hardcoded prefix also risked doubling to `/api/v1/api/v1/...` once
+ * KASUVIA_CRM_URL was actually set.
+ */
+import type { SdkConfig } from '../config'
+import type {
+  Review, Comment, ReviewCreate, ReviewUpdate, CommentCreate, CommentUpdate,
+  MerchantReplyCreate, ReviewModerationAction, CommentModerationAction,
+  ProductReviewsResponse, ProductCommentsResponse
+} from '../types/reviews'
+import { apiRequest, JSON_HEADERS, type ApiRequestOptions } from '../utils/http-client'
+
+export type {
+  Review, Comment, ReviewCreate, ReviewUpdate, CommentCreate, CommentUpdate,
+  MerchantReplyCreate, ReviewModerationAction, CommentModerationAction,
+  ProductReviewsResponse, ProductCommentsResponse
+}
+
+/**
+ * This service takes its identity from `config.authToken`/`config.
+ * storefrontApiKey`/`config.businessId` directly (unlike every other SDK
+ * service, which takes an explicit `accessToken` parameter) - preserved as-
+ * is here since callers (use-reviews.ts) already depend on this exact
+ * calling convention; only the underlying transport moved onto the shared
+ * client.
+ */
+function fetchWithConfig<T>(url: string, config: SdkConfig, options: ApiRequestOptions = {}): Promise<T> {
+  const headers: Record<string, string> = {
+    ...JSON_HEADERS,
+    Accept: 'application/json',
+    ...(options.headers as Record<string, string> | undefined),
+  }
+  if (config.storefrontApiKey) headers['X-Storefront-Key'] = config.storefrontApiKey
+  if (config.businessId) headers['X-Business-ID'] = config.businessId
+  if (config.authToken) headers['Authorization'] = `Bearer ${config.authToken}`
+
+  return apiRequest<T>(url, { ...options, headers, fallbackErrorMessage: options.fallbackErrorMessage ?? 'Request failed' })
+}
+
+/**
+ * Create a new review
+ */
+export async function createReview(
+  reviewData: ReviewCreate,
+  config: SdkConfig
+): Promise<Review> {
+  const url = `${config.backendUrls.crm}/reviews`
+  return fetchWithConfig<Review>(url, config, {
+    method: 'POST',
+    body: JSON.stringify(reviewData),
+    fallbackErrorMessage: 'Failed to create review',
+  })
+}
+
+/**
+ * Update an existing review
+ */
+export async function updateReview(
+  reviewId: string,
+  reviewData: ReviewUpdate,
+  config: SdkConfig
+): Promise<Review> {
+  const url = `${config.backendUrls.crm}/reviews/${reviewId}`
+  return fetchWithConfig<Review>(url, config, {
+    method: 'PUT',
+    body: JSON.stringify(reviewData),
+    fallbackErrorMessage: 'Failed to update review',
+  })
+}
+
+/**
+ * Get paginated reviews for a product
+ */
+export async function getProductReviews(
+  productId: string,
+  params: { page?: number; page_size?: number; moderation_status?: string } = {},
+  config: SdkConfig
+): Promise<ProductReviewsResponse> {
+  const queryParams = new URLSearchParams()
+  if (params.page) queryParams.append('page', params.page.toString())
+  if (params.page_size) queryParams.append('page_size', params.page_size.toString())
+  if (params.moderation_status) queryParams.append('moderation_status', params.moderation_status)
+
+  const url = `${config.backendUrls.crm}/products/${productId}/reviews?${queryParams.toString()}`
+  return fetchWithConfig<ProductReviewsResponse>(url, config, { fallbackErrorMessage: 'Failed to fetch product reviews' })
+}
+
+/**
+ * Create a new comment
+ */
+export async function createComment(
+  commentData: CommentCreate,
+  config: SdkConfig
+): Promise<Comment> {
+  const url = `${config.backendUrls.crm}/comments`
+  return fetchWithConfig<Comment>(url, config, {
+    method: 'POST',
+    body: JSON.stringify(commentData),
+    fallbackErrorMessage: 'Failed to create comment',
+  })
+}
+
+/**
+ * Update an existing comment
+ */
+export async function updateComment(
+  commentId: string,
+  commentData: CommentUpdate,
+  config: SdkConfig
+): Promise<Comment> {
+  const url = `${config.backendUrls.crm}/comments/${commentId}`
+  return fetchWithConfig<Comment>(url, config, {
+    method: 'PUT',
+    body: JSON.stringify(commentData),
+    fallbackErrorMessage: 'Failed to update comment',
+  })
+}
+
+/**
+ * Get paginated comments for a product
+ */
+export async function getProductComments(
+  productId: string,
+  params: { page?: number; page_size?: number; moderation_status?: string } = {},
+  config: SdkConfig
+): Promise<ProductCommentsResponse> {
+  const queryParams = new URLSearchParams()
+  if (params.page) queryParams.append('page', params.page.toString())
+  if (params.page_size) queryParams.append('page_size', params.page_size.toString())
+  if (params.moderation_status) queryParams.append('moderation_status', params.moderation_status)
+
+  const url = `${config.backendUrls.crm}/products/${productId}/comments?${queryParams.toString()}`
+  return fetchWithConfig<ProductCommentsResponse>(url, config, { fallbackErrorMessage: 'Failed to fetch product comments' })
+}
+
+/**
+ * Get pending reviews for moderation (merchant/staff only)
+ */
+export async function getPendingReviews(config: SdkConfig): Promise<Review[]> {
+  const url = `${config.backendUrls.crm}/admin/reviews/pending`
+  return fetchWithConfig<Review[]>(url, config, { fallbackErrorMessage: 'Failed to fetch pending reviews' })
+}
+
+/**
+ * Get pending comments for moderation (merchant/staff only)
+ */
+export async function getPendingComments(config: SdkConfig): Promise<Comment[]> {
+  const url = `${config.backendUrls.crm}/admin/comments/pending`
+  return fetchWithConfig<Comment[]>(url, config, { fallbackErrorMessage: 'Failed to fetch pending comments' })
+}
+
+/**
+ * Moderate a review (approve/reject) - merchant/staff only
+ */
+export async function moderateReview(
+  reviewId: string,
+  action: ReviewModerationAction,
+  config: SdkConfig
+): Promise<Review> {
+  const url = `${config.backendUrls.crm}/admin/reviews/${reviewId}/moderate`
+  return fetchWithConfig<Review>(url, config, {
+    method: 'POST',
+    body: JSON.stringify(action),
+    fallbackErrorMessage: 'Failed to moderate review',
+  })
+}
+
+/**
+ * Moderate a comment (approve/reject) - merchant/staff only
+ */
+export async function moderateComment(
+  commentId: string,
+  action: CommentModerationAction,
+  config: SdkConfig
+): Promise<Comment> {
+  const url = `${config.backendUrls.crm}/admin/comments/${commentId}/moderate`
+  return fetchWithConfig<Comment>(url, config, {
+    method: 'POST',
+    body: JSON.stringify(action),
+    fallbackErrorMessage: 'Failed to moderate comment',
+  })
+}
+
+/**
+ * Post a merchant reply to a review - merchant/staff only
+ */
+export async function merchantReplyToReview(
+  reviewId: string,
+  replyData: MerchantReplyCreate,
+  config: SdkConfig
+): Promise<Review> {
+  const url = `${config.backendUrls.crm}/admin/reviews/${reviewId}/reply`
+  return fetchWithConfig<Review>(url, config, {
+    method: 'POST',
+    body: JSON.stringify(replyData),
+    fallbackErrorMessage: 'Failed to post merchant reply',
+  })
+}

package/src/services/service-booking.service.ts

@@ -1,148 +1,245 @@
 /**
  * Service Booking Service
- * 
- * Handles service appointments and deliverables.
- * Stateless - all configuration passed as parameters.
+ *
+ * Handles service appointments (bookings) and their milestone/escrow
+ * sub-resource. Stateless - all configuration passed as parameters.
+ *
+ * REAL BUGS FIXED (2026-09-20) — every function in this file was rewritten
+ * against the real backend (kasuvia-store-management/app/api/v1/endpoints/
+ * service/bookings.py, app/schemas/service.py). Before this fix:
+ *   - getAvailableSlots called a nonexistent route (/service/available-slots/
+ *     {id}) with the wrong params (date_from/date_to) — the real route is
+ *     GET /catalog/products/{id}/available-slots?date=..., a single date.
+ *   - bookAppointment POSTed to a nonexistent route (/service/appointments/)
+ *     — the real route is POST /service/bookings/schedule.
+ *   - getAppointments typed its result as a plain array, but the real
+ *     response is the standard Kasuvia paginated envelope
+ *     ({results,count,page,page_size,total_pages}) — this was a CONFIRMED
+ *     LIVE CRASH: DashboardClient.tsx/DashboardAppointments.tsx called
+ *     .length/.filter() directly on the envelope object.
+ *   - cancelAppointment sent DELETE /service/bookings/{id} — that route is
+ *     owner/staff-only (require_permission("services:manage")), so a
+ *     customer got a 403; the real customer route is POST .../{id}/cancel.
+ *     It also never checked response.ok at all, silently swallowing failures.
+ *   - getDeliverables/approveDeliverable/requestRevision referenced a
+ *     "/service/projects/{order_id}/deliverables/..." resource that does not
+ *     exist anywhere in the codebase — replaced with the real milestone
+ *     endpoints (a different resource: escrow-style payment milestones on
+ *     a booking, not free-form deliverable files).
+ *   - No coverage existed for reschedule, dispute, or buyer-confirm — all
+ *     real, customer-facing routes.
  */
 import type { SdkConfig } from '../config'
 import type {
   ServiceAppointment,
   ServiceAppointmentCreatePayload,
-  AvailableSlot,
-  ServiceDeliverable,
-  DeliverableApprovalPayload,
+  CancelAppointmentPayload,
+  RescheduleAppointmentPayload,
+  DisputeAppointmentPayload,
+  ConfirmAppointmentPayload,
+  AvailableSlotsResponse,
+  ServiceMilestone,
+  ApproveMilestonePayload,
 } from '../types/services'
+import type { components } from '../generated/store-openapi'
+import { apiRequest, storefrontHeaders, authHeaders, JSON_HEADERS } from '../utils/http-client'
 
+// ─── Codegen drift-proofs (openapi/README.md — regenerate via `pnpm run codegen:rest`) ─
+// Unlike order.service.ts, this file's hand-written types (types/services/
+// index.ts) were already verified field-for-field correct against the real
+// backend Pydantic schemas (see that file's own header comment) - full
+// replacement would only add risk for zero gain. These type-level
+// assignments instead prove the match at compile time: if the real backend
+// schema ever adds/renames/retypes a field these three interfaces declare,
+// the corresponding line below fails to compile immediately (at `pnpm run
+// codegen:rest` + `tsc` time), the same drift-detection value Workstream 1
+// already proved for the GraphQL side, without touching working code.
+// (One real drift WAS found and fixed this way: ServiceMilestone.amount
+// was typed `number` but the real field is a Decimal-as-string.)
+type _ServiceAppointmentMatchesSchema = ServiceAppointment extends components['schemas']['ServiceBookingResponse'] ? true : never
+type _AvailableSlotsResponseMatchesSchema = AvailableSlotsResponse extends components['schemas']['AvailableSlotsResponse'] ? true : never
+type _ServiceMilestoneMatchesSchema = ServiceMilestone extends components['schemas']['ServiceMilestoneResponse'] ? true : never
+const _serviceAppointmentCheck: _ServiceAppointmentMatchesSchema = true
+const _availableSlotsCheck: _AvailableSlotsResponseMatchesSchema = true
+const _serviceMilestoneCheck: _ServiceMilestoneMatchesSchema = true
+void _serviceAppointmentCheck
+void _availableSlotsCheck
+void _serviceMilestoneCheck
+
+/** Standard Kasuvia pagination envelope — matches app/core/pagination.py's PaginatedResponse exactly. */
+export interface ServiceBookingsPage {
+  results: ServiceAppointment[]
+  count: number
+  page: number
+  page_size: number
+  total_pages: number
+}
+
+/**
+ * GET /catalog/products/{product_id}/available-slots — real "what times are
+ * open" for a SERVICE product on one date. `serviceable: false` means the
+ * business has no/ambiguous location config for this product (check
+ * `reason`); `available_slots` is always empty in that case, not an error.
+ */
 export async function getAvailableSlots(
   config: SdkConfig,
-  product_id: string,
-  date_from: string,
-  date_to: string
-): Promise<AvailableSlot[]> {
-  const response = await fetch(
-    `${config.backendUrls.store}/service/available-slots/${product_id}?date_from=${date_from}&date_to=${date_to}`,
+  productId: string,
+  date: string,
+  params?: { staffId?: string; locationId?: string; customerLatitude?: number; customerLongitude?: number }
+): Promise<AvailableSlotsResponse> {
+  const query = new URLSearchParams({ date })
+  if (params?.staffId) query.set('staff_id', params.staffId)
+  if (params?.locationId) query.set('location_id', params.locationId)
+  if (params?.customerLatitude !== undefined) query.set('customer_latitude', String(params.customerLatitude))
+  if (params?.customerLongitude !== undefined) query.set('customer_longitude', String(params.customerLongitude))
+
+  return apiRequest<AvailableSlotsResponse>(
+    `${config.backendUrls.store}/catalog/products/${productId}/available-slots?${query.toString()}`,
     {
-      headers: {
-        "X-Storefront-Key": config.storefrontApiKey,
-        "X-Business-ID": config.businessId,
-      },
+      headers: storefrontHeaders(config),
+      fallbackErrorMessage: 'Failed to get available slots',
     }
   )
-  if (!response.ok) throw new Error('Failed to get available slots')
-  return response.json()
 }
 
+/** POST /service/bookings/schedule */
 export async function bookAppointment(
   config: SdkConfig,
   accessToken: string,
   payload: ServiceAppointmentCreatePayload
 ): Promise<ServiceAppointment> {
-  const response = await fetch(`${config.backendUrls.store}/service/appointments/`, {
+  return apiRequest<ServiceAppointment>(`${config.backendUrls.store}/service/bookings/schedule`, {
     method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+    headers: { ...JSON_HEADERS, ...authHeaders(config, accessToken) },
     body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to book appointment',
   })
-  if (!response.ok) throw new Error('Failed to book appointment')
-  return response.json()
 }
 
-export async function getAppointments(config: SdkConfig, accessToken: string): Promise<ServiceAppointment[]> {
-  const response = await fetch(`${config.backendUrls.store}/service/bookings/my`, {
-    headers: {
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+/** GET /service/bookings/my — paginated. */
+export async function getAppointments(
+  config: SdkConfig,
+  accessToken: string,
+  params?: { status?: ServiceAppointment['status']; page?: number; page_size?: number }
+): Promise<ServiceBookingsPage> {
+  const query = new URLSearchParams()
+  if (params?.status) query.set('status', params.status)
+  if (params?.page) query.set('page', String(params.page))
+  if (params?.page_size) query.set('page_size', String(params.page_size))
+
+  return apiRequest<ServiceBookingsPage>(`${config.backendUrls.store}/service/bookings/my?${query.toString()}`, {
+    headers: authHeaders(config, accessToken),
+    fallbackErrorMessage: 'Failed to get appointments',
   })
-  if (!response.ok) throw new Error('Failed to get appointments')
-  return response.json()
 }
 
+/**
+ * GET /service/bookings/{id} — customer-reachable single-booking lookup,
+ * used by the paginated list's detail view (PATCH .../{id} is a separate,
+ * owner/staff-only route).
+ *
+ * REAL BUG FIXED (2026-09-22): this call shape was already correct, but the
+ * backend route it targeted didn't exist at all — `ServiceBookingRepository
+ * .get_by_id_and_business` was used internally by every merchant action
+ * (cancel/reschedule/dispute/assign/etc.) but never exposed as a customer
+ * GET route. Every real call to `AppointmentDetail.tsx` (via `useAppointment`)
+ * 404'd. Fixed by adding `GET /{booking_id}` to kasuvia-store-management's
+ * `service/bookings.py` (customer_id-scoped, same pattern as
+ * `customer_cancel_booking` — service bookings have no guest-checkout path,
+ * so no guest_email fallback is needed here unlike orders).
+ */
 export async function getAppointment(config: SdkConfig, accessToken: string, id: string): Promise<ServiceAppointment> {
-  const response = await fetch(`${config.backendUrls.store}/service/bookings/${id}`, {
-    headers: {
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+  return apiRequest<ServiceAppointment>(`${config.backendUrls.store}/service/bookings/${id}`, {
+    headers: authHeaders(config, accessToken),
+    fallbackErrorMessage: 'Failed to get appointment',
   })
-  if (!response.ok) throw new Error('Failed to get appointment')
-  return response.json()
 }
 
-export async function cancelAppointment(config: SdkConfig, accessToken: string, id: string): Promise<void> {
-  await fetch(`${config.backendUrls.store}/service/bookings/${id}`, {
-    method: 'DELETE',
-    headers: {
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+/** POST /service/bookings/{id}/cancel — the real customer-cancel route (DELETE .../{id} is owner/staff-only). */
+export async function cancelAppointment(
+  config: SdkConfig,
+  accessToken: string,
+  id: string,
+  payload?: CancelAppointmentPayload
+): Promise<ServiceAppointment> {
+  return apiRequest<ServiceAppointment>(`${config.backendUrls.store}/service/bookings/${id}/cancel`, {
+    method: 'POST',
+    headers: { ...JSON_HEADERS, ...authHeaders(config, accessToken) },
+    body: JSON.stringify(payload ?? {}),
+    fallbackErrorMessage: 'Failed to cancel appointment',
+  })
+}
+
+/** POST /service/bookings/{id}/reschedule — subject to the same cancellation_window_hours as a cancel. */
+export async function rescheduleAppointment(
+  config: SdkConfig,
+  accessToken: string,
+  id: string,
+  payload: RescheduleAppointmentPayload
+): Promise<ServiceAppointment> {
+  return apiRequest<ServiceAppointment>(`${config.backendUrls.store}/service/bookings/${id}/reschedule`, {
+    method: 'POST',
+    headers: { ...JSON_HEADERS, ...authHeaders(config, accessToken) },
+    body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to reschedule appointment',
   })
 }
 
-export async function getDeliverables(config: SdkConfig, accessToken: string, order_id: string): Promise<ServiceDeliverable[]> {
-  const response = await fetch(`${config.backendUrls.store}/service/projects/${order_id}/deliverables/`, {
-    headers: {
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+/** POST /service/bookings/{id}/dispute — freezes the escrow auto-release timer; requires a real reason. */
+export async function disputeAppointment(
+  config: SdkConfig,
+  accessToken: string,
+  id: string,
+  payload: DisputeAppointmentPayload
+): Promise<ServiceAppointment> {
+  return apiRequest<ServiceAppointment>(`${config.backendUrls.store}/service/bookings/${id}/dispute`, {
+    method: 'POST',
+    headers: { ...JSON_HEADERS, ...authHeaders(config, accessToken) },
+    body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to open dispute',
   })
-  if (!response.ok) throw new Error('Failed to get deliverables')
-  return response.json()
 }
 
-export async function approveDeliverable(
+/** POST /service/bookings/{id}/confirm — buyer confirms the service was completed. */
+export async function confirmAppointmentCompletion(
   config: SdkConfig,
   accessToken: string,
-  order_id: string,
-  deliverable_id: string
-): Promise<ServiceDeliverable> {
-  const response = await fetch(
-    `${config.backendUrls.store}/service/projects/${order_id}/deliverables/${deliverable_id}/approve`,
-    {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        "Authorization": `Bearer ${accessToken}`,
-        "X-Storefront-Key": config.storefrontApiKey,
-        "X-Business-ID": config.businessId,
-      },
-      body: JSON.stringify({ approved: true }),
-    }
-  )
-  if (!response.ok) throw new Error('Failed to approve deliverable')
-  return response.json()
+  id: string,
+  payload?: ConfirmAppointmentPayload
+): Promise<ServiceAppointment> {
+  return apiRequest<ServiceAppointment>(`${config.backendUrls.store}/service/bookings/${id}/confirm`, {
+    method: 'POST',
+    headers: { ...JSON_HEADERS, ...authHeaders(config, accessToken) },
+    body: JSON.stringify(payload ?? {}),
+    fallbackErrorMessage: 'Failed to confirm completion',
+  })
+}
+
+/** GET /service/bookings/{id}/milestones — escrow-style payment milestones for a milestone-based booking. */
+export async function getMilestones(config: SdkConfig, accessToken: string, bookingId: string): Promise<ServiceMilestone[]> {
+  return apiRequest<ServiceMilestone[]>(`${config.backendUrls.store}/service/bookings/${bookingId}/milestones`, {
+    headers: authHeaders(config, accessToken),
+    fallbackErrorMessage: 'Failed to get milestones',
+  })
 }
 
-export async function requestRevision(
+/** POST /service/bookings/{id}/milestones/{milestone_id}/approve — buyer approves a submitted milestone, triggering escrow release. */
+export async function approveMilestone(
   config: SdkConfig,
   accessToken: string,
-  order_id: string,
-  deliverable_id: string,
-  feedback: string
-): Promise<ServiceDeliverable> {
-  const response = await fetch(
-    `${config.backendUrls.store}/service/projects/${order_id}/deliverables/${deliverable_id}/revision`,
+  bookingId: string,
+  milestoneId: string,
+  payload?: ApproveMilestonePayload
+): Promise<ServiceMilestone> {
+  return apiRequest<ServiceMilestone>(
+    `${config.backendUrls.store}/service/bookings/${bookingId}/milestones/${milestoneId}/approve`,
     {
       method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        "Authorization": `Bearer ${accessToken}`,
-        "X-Storefront-Key": config.storefrontApiKey,
-        "X-Business-ID": config.businessId,
-      },
-      body: JSON.stringify({ approved: false, feedback }),
+      headers: { ...JSON_HEADERS, ...authHeaders(config, accessToken) },
+      body: JSON.stringify(payload ?? {}),
+      fallbackErrorMessage: 'Failed to approve milestone',
     }
   )
-  if (!response.ok) throw new Error('Failed to request revision')
-  return response.json()
 }
 
 // Service object export for backward compatibility
@@ -152,7 +249,9 @@ export const serviceBookingService = {
   getAppointments,
   getAppointment,
   cancelAppointment,
-  getDeliverables,
-  approveDeliverable,
-  requestRevision,
+  rescheduleAppointment,
+  disputeAppointment,
+  confirmAppointmentCompletion,
+  getMilestones,
+  approveMilestone,
 }