@kasuvia/sdk 0.0.8 → 0.0.9

package/src/services/bespoke.service.ts

@@ -1,25 +1,84 @@
 /**
  * Bespoke Service
- * 
- * Handles bespoke product availability checks.
+ *
+ * Handles bespoke product availability checks and the buyer side of the
+ * bespoke order deliverable proofing flow.
  * Stateless - all configuration passed as parameters.
  */
 import type { SdkConfig } from '../config'
-import type { BespokeAvailability } from '../types/consultations'
+import type { BespokeAvailability, BespokeDeliverableStatus } from '../types/consultations'
+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`) ─
+// Same approach as service-booking.service.ts's own comment: these prove
+// the hand-written types still match the real backend schema at compile
+// time, without a risky full rewrite of working code. Found and fixed one
+// real gap this way: BespokeDeliverableStatus was missing
+// bespoke_revision_notes entirely, a field the real backend has always
+// returned.
+type _BespokeAvailabilityMatchesSchema = BespokeAvailability extends components['schemas']['BespokeAvailabilityResponse'] ? true : never
+type _BespokeDeliverableStatusMatchesSchema = BespokeDeliverableStatus extends components['schemas']['BespokeStatusResponse'] ? true : never
+const _bespokeAvailabilityCheck: _BespokeAvailabilityMatchesSchema = true
+const _bespokeDeliverableStatusCheck: _BespokeDeliverableStatusMatchesSchema = true
+void _bespokeAvailabilityCheck
+void _bespokeDeliverableStatusCheck
+
+/**
+ * REAL BUG FIXED (2026-09-20): was calling `/bespoke/availability/{id}` —
+ * missing the `/capacity` segment. Confirmed against the real router
+ * (kasuvia-store-management/app/api/v1/endpoints/bespoke/capacity.py:184,
+ * registered under the `/bespoke/capacity` prefix): the real route is
+ * `/bespoke/capacity/availability/{id}`. Every bespoke availability check
+ * was 404ing.
+ */
 export async function checkAvailability(config: SdkConfig, product_id: string): Promise<BespokeAvailability> {
-  const response = await fetch(`${config.backendUrls.store}/bespoke/availability/${product_id}`, {
-    headers: {
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+  return apiRequest<BespokeAvailability>(`${config.backendUrls.store}/bespoke/capacity/availability/${product_id}`, {
+    headers: storefrontHeaders(config),
+    fallbackErrorMessage: 'Failed to check bespoke availability',
+  })
+}
+
+/**
+ * POST /orders/{order_id}/bespoke/approve — buyer approves the seller's
+ * submitted deliverable, starting the escrow release clock.
+ */
+export async function approveBespokeDeliverable(
+  config: SdkConfig,
+  accessToken: string,
+  orderId: string
+): Promise<BespokeDeliverableStatus> {
+  return apiRequest<BespokeDeliverableStatus>(`${config.backendUrls.store}/orders/${orderId}/bespoke/approve`, {
+    method: 'POST',
+    headers: { ...JSON_HEADERS, ...authHeaders(config, accessToken) },
+    body: JSON.stringify({}),
+    fallbackErrorMessage: 'Failed to approve deliverable',
   })
+}
 
-  if (!response.ok) throw new Error('Failed to check bespoke availability')
-  return response.json()
+/**
+ * POST /orders/{order_id}/bespoke/request-revision — buyer asks the seller
+ * to revise the submitted deliverable. Capped at 2 revisions server-side;
+ * beyond that, the backend escalates to manual review rather than refusing
+ * silently (see the real endpoint's own doc comment).
+ */
+export async function requestBespokeRevision(
+  config: SdkConfig,
+  accessToken: string,
+  orderId: string,
+  notes: string
+): Promise<BespokeDeliverableStatus> {
+  return apiRequest<BespokeDeliverableStatus>(`${config.backendUrls.store}/orders/${orderId}/bespoke/request-revision`, {
+    method: 'POST',
+    headers: { ...JSON_HEADERS, ...authHeaders(config, accessToken) },
+    body: JSON.stringify({ notes }),
+    fallbackErrorMessage: 'Failed to request revision',
+  })
 }
 
 // Service object export for backward compatibility
 export const bespokeService = {
   checkAvailability,
+  approveBespokeDeliverable,
+  requestBespokeRevision,
 }

package/src/services/cart.service.ts

@@ -1,11 +1,33 @@
 /**
  * Cart Service
- * 
- * Handles cart operations for both guest and authenticated users.
- * Stateless - all configuration passed as parameters.
+ *
+ * Handles cart operations for both guest and authenticated users via
+ * kasuvia-cart-management (Go/Huma). All cart operations target the
+ * cart-management service, which is the single source of truth for cart state.
+ *
+ * KEY CONSTRAINT — backend-resolved fields:
+ * kasuvia-cart-management resolves product_name, product_slug, image_url,
+ * variant_attributes, unit_price, is_bespoke, and product_type entirely
+ * server-side from kasuvia-store-management at add/merge time. These MUST NOT
+ * be sent in request payloads — only product_id, variant_id, quantity, and
+ * custom_measurements are accepted by the backend.
+ *
+ * Stateless — all configuration passed as parameters.
  */
 import type { SdkConfig } from '../config'
-import type { CartItem, CartResponse } from '../types/store'
+import { ProductTypeEnum, type CartItem, type CartResponse, type ProductType } from '../types/store'
+import { apiRequest, storefrontHeaders, authHeaders, JSON_HEADERS } from '../utils/http-client'
+
+// REAL BUG FIXED (2026-09-21): every fetch() in this file targeted
+// `config.backendUrls.store` (kasuvia-store-management) even though this
+// file's own header comment already documented that cart moved to
+// kasuvia-cart-management (a separate Go/Huma service, strangler-fig
+// migration). kasuvia-store-management's own router.py explicitly says
+// "Cart is NOT registered here anymore" — every one of these calls 404s
+// against `store`. Fixed by routing through `backendUrls.cart` instead,
+// which callers must now provide (kasuvia-cart-management, same
+// `/api/v1/cart/...` route shape it was ported from — only the base URL
+// changes).
 
 function parseItems(items: CartItem[]): CartItem[] {
   return items.map((item) => ({
@@ -17,63 +39,54 @@ function parseItems(items: CartItem[]): CartItem[] {
   }));
 }
 
+function guestHeaders(config: SdkConfig, guestSessionId: string, extra?: Record<string, string>): Record<string, string> {
+  return { ...extra, ...storefrontHeaders(config), 'X-Guest-Session': guestSessionId }
+}
+
 /**
  * Fetch guest cart from backend (Redis-backed).
  */
-export async function getGuestCart(config: SdkConfig, guestSessionId: string): Promise<CartItem[]> {
-  if (!guestSessionId) return []
+export async function getGuestCart(config: SdkConfig, guestSessionId: string): Promise<CartResponse> {
+  if (!guestSessionId) throw new Error('Guest session ID is required to fetch guest cart');
 
-  try {
-    const response = await fetch(`${config.backendUrls.store}/cart/`, {
-      headers: { 
-        "X-Storefront-Key": config.storefrontApiKey,
-        "X-Business-ID": config.businessId,
-        "X-Guest-Session": guestSessionId 
-      },
-    })
-    if (!response.ok) return []
-    const data = await response.json()
-    return parseItems(data.items || [])
-  } catch {
-    return []
-  }
+  const data = await apiRequest<CartResponse>(`${config.backendUrls.cart}/cart/`, {
+    headers: guestHeaders(config, guestSessionId),
+    fallbackErrorMessage: 'Failed to fetch guest cart',
+  })
+  return { ...data, items: parseItems(data.items || []) }
 }
 
 /**
  * Add item to guest cart (Redis-backed).
+ * Only product_id, variant_id, quantity, and custom_measurements are sent —
+ * all other fields are resolved server-side by kasuvia-cart-management.
  */
-export async function addToGuestCart(config: SdkConfig, guestSessionId: string, item: CartItem): Promise<CartItem[]> {
-  if (!guestSessionId) return []
+export async function addToGuestCart(
+  config: SdkConfig,
+  guestSessionId: string,
+  item: {
+    product_id: string
+    variant_id?: string | null
+    quantity: number
+    custom_measurements?: string | null
+  }
+): Promise<CartResponse> {
+  if (!guestSessionId) throw new Error('Guest session ID is required to add to guest cart');
 
   const payload = {
     product_id: item.product_id,
-    product_slug: item.product_slug,
-    product_name: item.product_name,
-    image: item.image,
-    variant_id: item.variant_id,
-    variant_attributes:
-      typeof item.variant_attributes === "string"
-        ? item.variant_attributes
-        : JSON.stringify(item.variant_attributes),
-    unit_price: item.unit_price,
+    variant_id: item.variant_id ?? undefined,
     quantity: item.quantity,
-    custom_measurements: item.custom_measurements,
-    is_bespoke: item.is_bespoke,
+    custom_measurements: item.custom_measurements ?? undefined,
   }
 
-  const response = await fetch(`${config.backendUrls.store}/cart/`, {
+  const data = await apiRequest<CartResponse>(`${config.backendUrls.cart}/cart/`, {
     method: 'POST',
-    headers: { 
-      'Content-Type': 'application/json',
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-      "X-Guest-Session": guestSessionId 
-    },
+    headers: guestHeaders(config, guestSessionId, JSON_HEADERS),
     body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to add to guest cart',
   })
-  if (!response.ok) return []
-  const data = await response.json()
-  return parseItems(data.items || [])
+  return { ...data, items: parseItems(data.items || []) }
 }
 
 /**
@@ -84,59 +97,60 @@ export async function updateGuestCartItemQuantity(
   guestSessionId: string,
   itemId: string,
   quantity: number
-): Promise<CartItem[]> {
-  if (!guestSessionId) return []
+): Promise<CartResponse> {
+  if (!guestSessionId) throw new Error('Guest session ID is required to update guest cart item');
 
-  const response = await fetch(`${config.backendUrls.store}/cart/${itemId}`, {
+  const data = await apiRequest<CartResponse>(`${config.backendUrls.cart}/cart/${itemId}`, {
     method: 'PATCH',
-    headers: { 
-      'Content-Type': 'application/json',
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-      "X-Guest-Session": guestSessionId 
-    },
+    headers: guestHeaders(config, guestSessionId, JSON_HEADERS),
     body: JSON.stringify({ quantity }),
+    fallbackErrorMessage: 'Failed to update guest cart item',
   })
-  if (!response.ok) return []
-  const data = await response.json()
-  return parseItems(data.items || [])
+  return { ...data, items: parseItems(data.items || []) }
 }
 
 /**
  * Remove an item from the guest cart.
+ *
+ * REAL BUG FIXED (2026-09-22), live-reproduced: this used to type its
+ * result as `CartResponse` and read `data.items` off it, but the real
+ * backend's `DELETE /cart/{item_id}` returns `204 No Content` with a
+ * genuinely empty body (confirmed live: `HTTP_STATUS:204 BODY_LENGTH:0`) -
+ * `apiRequest` resolves an empty body to `undefined`, so `data.items`
+ * threw `TypeError: Cannot read properties of undefined (reading 'items')`
+ * on every real delete. The item really was removed server-side (the
+ * DELETE request itself succeeded), but the thrown error sent
+ * `removeFromCartMutation` down `onError` instead of `onSuccess`, so
+ * `queryClient.invalidateQueries` never ran - a customer's cart kept
+ * showing the "removed" item until something else (a full page reload)
+ * happened to trigger a fresh, uncached fetch. Matches `clearGuestCart`'s
+ * existing `Promise<void>` shape, which was already correct for this same
+ * "backend returns no body" pattern.
  */
 export async function removeFromGuestCart(
   config: SdkConfig,
   guestSessionId: string,
   itemId: string
-): Promise<CartItem[]> {
-  if (!guestSessionId) return []
+): Promise<void> {
+  if (!guestSessionId) throw new Error('Guest session ID is required to remove from guest cart');
 
-  await fetch(`${config.backendUrls.store}/cart/${itemId}`, {
+  await apiRequest(`${config.backendUrls.cart}/cart/${itemId}`, {
     method: 'DELETE',
-    headers: { 
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-      "X-Guest-Session": guestSessionId 
-    },
+    headers: guestHeaders(config, guestSessionId),
+    fallbackErrorMessage: 'Failed to remove item from guest cart',
   })
-
-  return getGuestCart(config, guestSessionId)
 }
 
 /**
  * Clear the entire guest cart.
  */
 export async function clearGuestCart(config: SdkConfig, guestSessionId: string): Promise<void> {
-  if (!guestSessionId) return
+  if (!guestSessionId) throw new Error('Guest session ID is required to clear guest cart');
 
-  await fetch(`${config.backendUrls.store}/cart/clear`, {
+  await apiRequest(`${config.backendUrls.cart}/cart/clear`, {
     method: 'DELETE',
-    headers: { 
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-      "X-Guest-Session": guestSessionId 
-    },
+    headers: guestHeaders(config, guestSessionId),
+    fallbackErrorMessage: 'Failed to clear guest cart',
   })
 }
 
@@ -145,54 +159,54 @@ export async function clearGuestCart(config: SdkConfig, guestSessionId: string):
  */
 export async function getCart(config: SdkConfig, accessToken?: string | null): Promise<CartResponse> {
   if (!accessToken) {
-    return { id: '', items: [], subtotal: 0, total: 0, product_type: 'physical' } as any;
+    throw new Error('Access token is required to fetch authenticated cart');
   }
-  const response = await fetch(`${config.backendUrls.store}/cart/`, {
-    headers: { 
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+  const data = await apiRequest<CartResponse>(`${config.backendUrls.cart}/cart/`, {
+    headers: authHeaders(config, accessToken),
+    fallbackErrorMessage: 'Failed to fetch cart',
   })
-  if (!response.ok) throw new Error('Failed to fetch cart')
-  const data = await response.json()
-  const parsedItems = parseItems(data.items || [])
-  return { ...data, items: parsedItems }
+  return { ...data, items: parseItems(data.items || []) }
 }
 
 /**
  * Add item to authenticated user's cart.
+ * Only product_id, variant_id, quantity, and custom_measurements are sent —
+ * all other fields are resolved server-side by kasuvia-cart-management.
  */
 export async function addToCart(
   config: SdkConfig,
   accessToken: string,
   item: {
     product_id: string
-    product_slug: string
-    product_name: string
-    image?: string
-    variant_id?: string
-    variant_attributes?: string
-    unit_price: number
+    variant_id?: string | null
     quantity: number
-    custom_measurements?: string
-    is_bespoke: boolean
+    custom_measurements?: string | null
+    // These fields are accepted from the caller for UI convenience but are
+    // NOT forwarded to the backend — kasuvia-cart-management resolves them
+    // server-side. Declared here so callers don't need to strip them.
+    product_slug?: string
+    product_name?: string
+    image_url?: string
+    variant_attributes?: string
+    unit_price?: number
+    is_bespoke?: boolean
   }
 ): Promise<CartResponse> {
-  const response = await fetch(`${config.backendUrls.store}/cart/`, {
+  // Only send the fields the backend accepts — strip everything else.
+  const payload = {
+    product_id: item.product_id,
+    variant_id: item.variant_id ?? undefined,
+    quantity: item.quantity,
+    custom_measurements: item.custom_measurements ?? undefined,
+  }
+
+  const data = await apiRequest<CartResponse>(`${config.backendUrls.cart}/cart/`, {
     method: 'POST',
-    headers: { 
-      'Content-Type': 'application/json',
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
-    body: JSON.stringify(item),
+    headers: { ...JSON_HEADERS, ...authHeaders(config, accessToken) },
+    body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to add to cart',
   })
-  if (!response.ok) throw new Error('Failed to add to cart')
-  const data = await response.json()
-  const parsedItems = parseItems(data.items || [])
-  return { ...data, items: parsedItems }
+  return { ...data, items: parseItems(data.items || []) }
 }
 
 /**
@@ -204,144 +218,99 @@ export async function updateCartItem(
   itemId: string,
   quantity: number
 ): Promise<CartResponse> {
-  const response = await fetch(`${config.backendUrls.store}/cart/${itemId}`, {
+  const data = await apiRequest<CartResponse>(`${config.backendUrls.cart}/cart/${itemId}`, {
     method: 'PATCH',
-    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({ quantity }),
+    fallbackErrorMessage: 'Failed to update cart item',
   })
-  if (!response.ok) throw new Error('Failed to update cart item')
-  const data = await response.json()
-  const parsedItems = parseItems(data.items || [])
-  return { ...data, items: parsedItems }
+  return { ...data, items: parseItems(data.items || []) }
 }
 
 /**
  * Remove item from authenticated user's cart.
+ * Same real bug/fix as removeFromGuestCart above - see its doc comment.
  */
 export async function removeFromCart(
   config: SdkConfig,
   accessToken: string,
   itemId: string
-): Promise<CartResponse> {
-  await fetch(`${config.backendUrls.store}/cart/${itemId}`, {
+): Promise<void> {
+  await apiRequest(`${config.backendUrls.cart}/cart/${itemId}`, {
     method: 'DELETE',
-    headers: { 
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+    headers: authHeaders(config, accessToken),
+    fallbackErrorMessage: 'Failed to remove cart item',
   })
-  return getCart(config, accessToken)
 }
 
 /**
  * Clear authenticated user's cart.
  */
 export async function clearCart(config: SdkConfig, accessToken: string): Promise<void> {
-  await fetch(`${config.backendUrls.store}/cart/clear`, {
+  await apiRequest(`${config.backendUrls.cart}/cart/clear`, {
     method: 'DELETE',
-    headers: { 
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+    headers: authHeaders(config, accessToken),
+    fallbackErrorMessage: 'Failed to clear cart',
   })
 }
 
 /**
- * Merge guest cart (from Redis) into authenticated user's DB cart.
+ * Merge guest cart items into the authenticated customer's cart.
+ *
+ * The backend (POST /api/v1/cart/merge) accepts only:
+ *   { items: [{ product_id, variant_id?, quantity, custom_measurements? }] }
+ * Product name, image, price, type are all re-resolved server-side.
+ *
+ * Sends X-Guest-Session so the backend can atomically delete the guest
+ * cart (best-effort) after merging.
  */
 export async function mergeGuestCart(
   config: SdkConfig,
   accessToken: string,
-  guestSessionId: string
+  guestSessionId: string,
+  guestItems: Pick<CartItem, 'product_id' | 'variant_id' | 'quantity' | 'custom_measurements'>[]
 ): Promise<CartResponse> {
-  const guestItems = guestSessionId ? await getGuestCart(config, guestSessionId) : []
-  
-  if (guestItems.length === 0) {
-    return getCart(config, accessToken)
-  }
-
   const payloadItems = guestItems.map((item) => ({
     product_id: item.product_id,
-    product_slug: item.product_slug,
-    product_name: item.product_name,
-    image: item.image,
-    variant_id: item.variant_id,
-    variant_attributes:
-      typeof item.variant_attributes === "string"
-        ? item.variant_attributes
-        : JSON.stringify(item.variant_attributes ?? {}),
-    unit_price: item.unit_price,
+    variant_id: item.variant_id ?? undefined,
     quantity: item.quantity,
-    custom_measurements:
-      typeof item.custom_measurements === "string"
-        ? item.custom_measurements
-        : JSON.stringify(item.custom_measurements ?? {}),
-    is_bespoke: item.is_bespoke,
+    custom_measurements: item.custom_measurements ?? undefined,
   }))
 
-  const headers: Record<string, string> = {
-    'Content-Type': 'application/json',
-    "Authorization": `Bearer ${accessToken}`,
-    "X-Storefront-Key": config.storefrontApiKey,
-    "X-Business-ID": config.businessId,
-  }
+  const headers: Record<string, string> = { ...JSON_HEADERS, ...authHeaders(config, accessToken) }
   if (guestSessionId) {
     headers["X-Guest-Session"] = guestSessionId
   }
 
-  const response = await fetch(`${config.backendUrls.store}/cart/merge`, {
+  const data = await apiRequest<CartResponse>(`${config.backendUrls.cart}/cart/merge`, {
     method: 'POST',
     headers,
     body: JSON.stringify({ items: payloadItems }),
+    fallbackErrorMessage: 'Failed to merge guest cart',
   })
-  if (!response.ok) throw new Error('Failed to merge guest cart')
-  const data = await response.json()
   return { ...data, items: parseItems(data.items || []) }
 }
 
 /**
- * Convenience wrapper: merge guest cart if it has items (called post-login).
+ * Convenience wrapper: fetch guest cart and merge if it has items (called post-login).
  */
 export async function mergeGuestCartIfPresent(
   config: SdkConfig,
   accessToken: string,
   guestSessionId: string
 ): Promise<void> {
-  try {
-    const guestItems = await getGuestCart(config, guestSessionId)
-    if (guestItems.length === 0) return
-    await mergeGuestCart(config, accessToken, guestSessionId)
-  } catch (error) {
-    console.warn("[Cart] Failed to merge guest cart:", error)
-  }
-}
-
-/**
- * Returns 0 — count is now server-driven. Use the hook instead.
- * Kept for backward compatibility.
- */
-export function getGuestCartCount(): number {
-  return 0
-}
-
-/**
- * Returns 0 — subtotal is now server-driven.
- * Kept for backward compatibility.
- */
-export function getGuestCartSubtotal(): number {
-  return 0
+  const guestCart = await getGuestCart(config, guestSessionId)
+  if (!guestCart.items.length) return
+  await mergeGuestCart(config, accessToken, guestSessionId, guestCart.items)
 }
 
 /**
- * Derive product type from items (guest cart, no backend lookup needed).
+ * Helper to get a guest cart's product type (for type-mismatch checks before adding an item).
  */
-export function getGuestCartProductType(): "physical" | "digital" | "bespoke" {
-  return "physical"
+export function getGuestCartProductType(items?: CartItem[]): ProductType | null {
+  if (!items || !items.length) return null;
+  const types = new Set(items.map(i => i.product_type).filter(Boolean));
+  if (types.size === 0) return null;
+  if (types.size === 1) return ([...types][0] as ProductType) ?? null;
+  return ProductTypeEnum.PHYSICAL;
 }