@kasuvia/sdk 0.0.8 → 0.0.9

package/src/services/logistics.service.ts

@@ -1,22 +1,13 @@
 /**
  * Logistics Service
- * 
+ *
  * Handles shipping rates and address validation.
  * Stateless - all configuration passed as parameters.
  */
 import type { SdkConfig } from '../config'
 import type { ShippingRatesResponse } from '../types/store/shipping'
-import type { Product, ProductVariant } from '../types/store'
-
-export interface CartItemPayload {
-  product: {
-    name: string
-    price: number
-    weight: number
-  }
-  variant: ProductVariant | null
-  quantity: number
-}
+import type { components } from '../generated/store-openapi'
+import { apiRequest, storefrontHeaders, JSON_HEADERS } from '../utils/http-client'
 
 export interface RateAddress {
   city: string
@@ -24,11 +15,28 @@ export interface RateAddress {
   country: string
 }
 
+/**
+ * REAL BUG FIXED (2026-09-20): this request shape used to be `{cart_items,
+ * origin_address, destination_address, currency?, shipping_method?}` —
+ * completely stale against the real backend. Confirmed against the real
+ * Pydantic schema (kasuvia-store-management/app/schemas/logistics.py:121-144,
+ * `ShippingRatesRequest`), which explicitly documents why: "No origin_address
+ * field — the server resolves the fulfilling StoreLocation itself... A
+ * client-supplied origin would either have to be silently ignored or
+ * silently trusted over the resolved location; neither is acceptable, so it
+ * isn't accepted at all." The server also fetches cart items itself from
+ * `cart_id` (server-side cart as source of truth, preventing client-side
+ * cart manipulation) rather than trusting a client-submitted item list.
+ * Sending the old shape meant every physical checkout's shipping-rates call
+ * was missing the required `cart_id` field entirely and would always 422.
+ */
 export interface ShippingRatesRequest {
-  cart_items: CartItemPayload[]
-  origin_address: RateAddress
+  cart_id: string
   destination_address: RateAddress
-  currency?: string
+  currency: string
+  shipping_method?: 'carrier' | 'self_pickup'
+  /** Required when shipping_method is 'self_pickup' — see GET /logistics/pickup-locations. */
+  pickup_location_id?: string
 }
 
 /**
@@ -38,43 +46,34 @@ export async function getShippingRates(
   config: SdkConfig,
   payload: ShippingRatesRequest
 ): Promise<ShippingRatesResponse> {
-  const response = await fetch(`${config.backendUrls.store}/logistics/shipping/rates`, {
+  return apiRequest<ShippingRatesResponse>(`${config.backendUrls.store}/logistics/shipping/rates`, {
     method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+    headers: { ...JSON_HEADERS, ...storefrontHeaders(config) },
     body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to get shipping rates',
   })
-  if (!response.ok) throw new Error('Failed to get shipping rates')
-  return response.json()
 }
 
 /**
- * Fetch the seller's registered shipping address.
+ * Result of independently forward-geocoding the typed street address via
+ * LocationIQ and cross-checking it against Terminal Africa's own (city/
+ * state/country-only, street-line-blind) validation. See
+ * app/services/address_trust_service.py on the backend. Only present when
+ * Terminal Africa itself reported the address valid.
  */
-export async function getSellerShippingAddress(config: SdkConfig): Promise<{
-  terminal_address_id: string | null
-  address_details: {
-    city: string
-    state: string
-    country: string
-    line1: string
-    line2: string
-    zip: string
+export interface AddressTrustResult {
+  trusted: boolean
+  confidence: 'high' | 'medium' | 'low' | 'unavailable'
+  reason: string | null
+  resolved: {
+    latitude: number
+    longitude: number
+    display_name: string
+    city: string | null
+    state: string | null
+    country: string | null
   } | null
-  business_id: string
-  message: string
-}> {
-  const response = await fetch(`${config.backendUrls.store}/logistics/shipping-address`, {
-    headers: {
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
-  })
-  if (!response.ok) throw new Error('Failed to get seller shipping address')
-  return response.json()
+  plus_code: string | null
 }
 
 /**
@@ -100,23 +99,206 @@ export async function validateShippingAddress(
   data?: unknown
   cities?: Array<{ name: string; city_id: string; stateCode: string; countryCode: string }>
   states?: Array<{ name: string; code: string; countryCode: string }>
+  /** Street-level trust check — only present when valid is true. See AddressTrustResult. */
+  address_trust?: AddressTrustResult
 }> {
-  const response = await fetch(`${config.backendUrls.store}/logistics/shipping-address/validate`, {
+  return apiRequest(`${config.backendUrls.store}/logistics/shipping-address/validate`, {
     method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+    headers: { ...JSON_HEADERS, ...storefrontHeaders(config) },
     body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to validate shipping address',
+  })
+}
+
+export interface PickupLocation {
+  id: string
+  name: string
+  description: string | null
+  address: {
+    line1: string
+    line2: string | null
+    city: string
+    state: string
+    country: string
+    postal_code: string
+  }
+  coordinates: { latitude: number; longitude: number }
+  /** km from the coordinates passed to listPickupLocations, or null if none were passed. */
+  distance_km: number | null
+  operating_hours: Record<string, string> | null
+}
+
+/**
+ * List the business's active pickup locations, so the customer can choose
+ * one at checkout for shipping_method="self_pickup" instead of the merchant
+ * assigning one blindly after the fact. Pass the customer's shipping
+ * coordinates to sort nearest-first.
+ */
+export interface PickupLocationsResult {
+  locations: PickupLocation[]
+}
+
+async function fetchLocationList(
+  config: SdkConfig,
+  path: 'pickup-locations' | 'locations',
+  coords: { latitude: number; longitude: number } | undefined,
+  fallbackErrorMessage: string
+): Promise<PickupLocationsResult> {
+  const params = new URLSearchParams()
+  if (coords) {
+    params.set('latitude', String(coords.latitude))
+    params.set('longitude', String(coords.longitude))
+  }
+  const qs = params.toString()
+  return apiRequest(`${config.backendUrls.store}/logistics/${path}${qs ? `?${qs}` : ''}`, {
+    headers: storefrontHeaders(config),
+    fallbackErrorMessage,
   })
-  if (!response.ok) throw new Error('Failed to validate shipping address')
-  return response.json()
 }
 
+export async function listPickupLocations(
+  config: SdkConfig,
+  coords?: { latitude: number; longitude: number }
+): Promise<PickupLocationsResult> {
+  return fetchLocationList(config, 'pickup-locations', coords, 'Failed to list pickup locations')
+}
+
+/**
+ * List ALL of the business's active locations (not just pickup-eligible
+ * ones) — the set a customer needs to choose from for an 'at_business'
+ * service appointment when the business runs more than one branch. Sibling
+ * of listPickupLocations, same response shape (PickupLocationsResult),
+ * different backend filter (GET /logistics/locations, no
+ * is_pickup_location gate).
+ */
+export async function listBusinessLocations(
+  config: SdkConfig,
+  coords?: { latitude: number; longitude: number }
+): Promise<PickupLocationsResult> {
+  return fetchLocationList(config, 'locations', coords, 'Failed to list business locations')
+}
+
+/**
+ * Reverse geocode coordinates to address components using backend LocationIQ service.
+ */
+export interface ReverseGeocodeResult {
+  city: string | null
+  state: string | null
+  country: string | null
+  country_code: string | null
+  display_name: string | null
+}
+
+export async function reverseGeocode(
+  config: SdkConfig,
+  payload: { latitude: number; longitude: number }
+): Promise<ReverseGeocodeResult> {
+  return apiRequest(`${config.backendUrls.store}/logistics/reverse-geocode`, {
+    method: 'POST',
+    headers: { ...JSON_HEADERS, ...storefrontHeaders(config) },
+    body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to reverse geocode coordinates',
+  })
+}
+
+/**
+ * Decode a Plus Code to coordinates.
+ */
+export interface PlusCodeDecodeResult {
+  latitude: number
+  longitude: number
+  latitude_lo: number
+  longitude_hi: number
+  plus_code: string
+}
+
+export async function decodePlusCode(
+  config: SdkConfig,
+  payload: { plus_code: string }
+): Promise<PlusCodeDecodeResult> {
+  return apiRequest(`${config.backendUrls.store}/logistics/plus-code/decode`, {
+    method: 'POST',
+    headers: { ...JSON_HEADERS, ...storefrontHeaders(config) },
+    body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to decode Plus Code',
+  })
+}
+
+/**
+ * As-you-type address autocomplete suggestions.
+ */
+export interface AddressSuggestionResult {
+  place_id: string
+  display_name: string
+  line1: string
+  city: string | null
+  state: string | null
+  postal_code: string | null
+  country: string | null
+  country_code: string | null
+  latitude: number | null
+  longitude: number | null
+}
+
+export interface AddressAutocompleteResult {
+  results: AddressSuggestionResult[]
+}
+
+export async function autocompleteAddress(
+  config: SdkConfig,
+  q: string,
+  country?: string
+): Promise<AddressAutocompleteResult> {
+  const params = new URLSearchParams()
+  params.set('q', q)
+  if (country) params.set('country', country)
+
+  return apiRequest(`${config.backendUrls.store}/logistics/address/autocomplete?${params.toString()}`, {
+    headers: storefrontHeaders(config),
+    fallbackErrorMessage: 'Failed to autocomplete address',
+  })
+}
+
+// ─── Codegen drift-proofs (openapi/README.md — regenerate via `pnpm run codegen:rest`) ─
+// Same approach as the other 3 target files' own comments. `getShippingRates`
+// and `validateShippingAddress` are deliberately NOT checked here:
+// GET /logistics/shipping/rates passes through Terminal Africa's own
+// response envelope as a raw dict (no Kasuvia-owned schema exists to check
+// against - a third party's contract, not this platform's), and
+// POST /logistics/shipping-address/validate similarly has no
+// response_model= (confirmed absent, same underlying gap class as
+// pickup-locations was until this pass, but out of scope for this initial
+// sweep - flagged here rather than silently left unchecked with no
+// explanation). PickupLocationsResult/ReverseGeocodeResult/
+// PlusCodeDecodeResult/AddressAutocompleteResult all have real backend
+// schemas and are checked below - PickupLocationsResponse's
+// response_model was added to the backend as part of this exact change
+// (previously also a raw-dict gap).
+// `operating_hours` is excluded from this check: it's a schemaless
+// `Dict[str, Any]` on the backend, which openapi-typescript can only infer
+// as `Record<string, never>` (an empty object) - a known tooling
+// imprecision (same class as shipping_address/variant_details elsewhere),
+// not a real type mismatch, so it would fail this check even when correct.
+type _PickupLocationsMatchesSchema = Omit<PickupLocationsResult['locations'][number], 'operating_hours'> extends Omit<components['schemas']['PickupLocationItem'], 'operating_hours'> ? true : never
+type _ReverseGeocodeMatchesSchema = ReverseGeocodeResult extends components['schemas']['ReverseGeocodeResponse'] ? true : never
+type _PlusCodeDecodeMatchesSchema = PlusCodeDecodeResult extends components['schemas']['PlusCodeDecodeResponse'] ? true : never
+type _AddressAutocompleteMatchesSchema = AddressAutocompleteResult extends components['schemas']['AddressAutocompleteResponse'] ? true : never
+const _pickupLocationsCheck: _PickupLocationsMatchesSchema = true
+const _reverseGeocodeCheck: _ReverseGeocodeMatchesSchema = true
+const _plusCodeDecodeCheck: _PlusCodeDecodeMatchesSchema = true
+const _addressAutocompleteCheck: _AddressAutocompleteMatchesSchema = true
+void _pickupLocationsCheck
+void _reverseGeocodeCheck
+void _plusCodeDecodeCheck
+void _addressAutocompleteCheck
+
 // Service object for backward compatibility
 export const logisticsService = {
   getShippingRates,
-  getSellerShippingAddress,
   validateShippingAddress,
+  listPickupLocations,
+  listBusinessLocations,
+  reverseGeocode,
+  decodePlusCode,
+  autocompleteAddress,
 }

package/src/services/media.service.ts

@@ -0,0 +1,115 @@
+/**
+ * Media Upload Service
+ *
+ * The real 3-step direct-to-R2 upload orchestration (presigned URL → PUT →
+ * confirm) that a browser client actually needs to run. Distinct from
+ * `auth.service.ts`'s `getPresignedUploadUrl`/`confirmMediaUpload`, which
+ * take an explicit bearer `accessToken` and are meant for server-side use
+ * (Next.js Route Handlers reading a customer's httpOnly cookie) — a "use
+ * client" component has no access token value in JS at all in that model,
+ * only the cookie, so it calls two thin same-origin proxy routes instead
+ * (`credentials: 'include'`) that wrap those same two SDK functions
+ * server-side.
+ *
+ * REAL DUPLICATION FIXED (2026-09-22): this exact 3-step sequence had been
+ * hand-written independently in two different kasuvia-storefront components
+ * (BespokeStep.tsx, ProductReviews.tsx) — identical logic, copy-pasted, with
+ * no shared SDK function to reuse. A second storefront project would have
+ * had to write it a third time. The two endpoint paths are parameterized
+ * (defaulting to the same `/api/auth/media/*` convention this storefront
+ * already uses) precisely so a *different* storefront that names its proxy
+ * routes differently can still use this function without a fork.
+ */
+import { apiRequest, JSON_HEADERS } from '../utils/http-client'
+import type { MediaAsset } from '../types/media'
+import type { PresignedUploadUrlResponse } from './auth.service'
+
+export interface UploadMediaFileParams {
+  file: File
+  /** e.g. "review", "digital_product" — matches kasuvia-media-system's context_validation.py. */
+  context: string
+  entityId: string
+  affiliation?: string
+  ownerId?: string
+  presignedUrlEndpoint?: string
+  confirmUploadEndpoint?: string
+}
+
+/**
+ * Upload one file end-to-end: request a presigned URL, PUT the file
+ * directly to R2, then confirm the upload to get back a real MediaAsset.
+ */
+export async function uploadMediaFile(params: UploadMediaFileParams): Promise<MediaAsset> {
+  const presignedUrlEndpoint = params.presignedUrlEndpoint ?? '/api/auth/media/presigned-url'
+  const confirmUploadEndpoint = params.confirmUploadEndpoint ?? '/api/auth/media/confirm-upload'
+
+  const { presigned_url, storage_path } = await apiRequest<PresignedUploadUrlResponse>(presignedUrlEndpoint, {
+    method: 'POST',
+    headers: JSON_HEADERS,
+    credentials: 'include',
+    body: JSON.stringify({
+      filename: params.file.name,
+      content_type: params.file.type,
+      context: params.context,
+      entity_id: params.entityId,
+      affiliation: params.affiliation,
+      owner_id: params.ownerId,
+    }),
+    fallbackErrorMessage: 'Could not start upload',
+  })
+
+  const putResponse = await fetch(presigned_url, {
+    method: 'PUT',
+    headers: { 'Content-Type': params.file.type },
+    body: params.file,
+  })
+  if (!putResponse.ok) {
+    throw new Error(`Failed to upload ${params.file.name}`)
+  }
+
+  return apiRequest<MediaAsset>(confirmUploadEndpoint, {
+    method: 'POST',
+    headers: JSON_HEADERS,
+    credentials: 'include',
+    body: JSON.stringify({
+      storage_path,
+      entity_id: params.entityId,
+      original_filename: params.file.name,
+      content_type: params.file.type,
+      size: params.file.size,
+      context: params.context,
+      affiliation: params.affiliation,
+      owner_id: params.ownerId,
+    }),
+    fallbackErrorMessage: `Could not confirm upload of ${params.file.name}`,
+  })
+}
+
+export interface UploadMediaFilesResult {
+  assets: MediaAsset[]
+  errors: { file: string; message: string }[]
+}
+
+/**
+ * Upload several files, one at a time (sequential — real progress feedback
+ * per file rather than an opaque Promise.all batch). A single file's
+ * failure does not abort the rest: matches the original BespokeStep/
+ * ProductReviews behaviour of keeping whatever succeeded before a later
+ * file failed, rather than discarding it. The caller decides how to present
+ * `errors` (e.g. one toast per failed filename).
+ */
+export async function uploadMediaFiles(
+  files: File[],
+  params: Omit<UploadMediaFileParams, 'file'>
+): Promise<UploadMediaFilesResult> {
+  const assets: MediaAsset[] = []
+  const errors: { file: string; message: string }[] = []
+  for (const file of files) {
+    try {
+      assets.push(await uploadMediaFile({ ...params, file }))
+    } catch (err) {
+      errors.push({ file: file.name, message: err instanceof Error ? err.message : 'Upload failed' })
+    }
+  }
+  return { assets, errors }
+}