@kasuvia/sdk 0.0.8 → 0.0.9

package/src/services/order.service.ts

@@ -6,20 +6,82 @@
  */
 import type { SdkConfig } from '../config'
 import type { Order, OrderStatus, FindOrderParams, CreateOrderParams, OrderItem } from '../types/store'
-import type { DeliveryAddress } from '../types/store'
+import type { components } from '../generated/store-openapi'
+import { apiRequest, ApiError, storefrontHeaders, authHeaders, JSON_HEADERS } from '../utils/http-client'
+
+// ─── Generated types (openapi/README.md — regenerate via `pnpm run codegen:rest`) ─
+// REAL BUG FOUND (2026-09-23) via this exact codegen initiative: the real
+// OrderResponse schema (kasuvia-store-management's app/schemas/order.py)
+// carries NO tracking_number/delivery_status/carrier_name/carrier_slug/
+// terminal_rate_id/terminal_shipment_id/shipping_address/shipping_surcharge_*/
+// declared_weight_kg/actual_weight_kg/pickup_verification_*/pickup_qr_payload
+// fields at its top level at all - confirmed by reading OrderBase/
+// OrderResponse's actual field lists directly, not just the generated
+// output. Every one of these genuinely lives nested under
+// `physical_fulfillment` (see PhysicalFulfillmentResponse below) - "One
+// nested block per product type, instead of ~35 flat fields on OrderBase"
+// per that file's own Order Schema Refactor comment. RawOrder/
+// normaliseStorefrontOrder below used to read every one of these as a flat
+// top-level field, so they were silently undefined on every real order -
+// a customer's tracking number, carrier, delivery status, and shipping
+// address never actually rendered anywhere on the storefront. Fixed to
+// read from the real nested location, same pattern already correctly
+// applied to bespoke_fulfillment (see deriveCustomerName/
+// normaliseStorefrontOrder's existing bespoke_fulfillment-first reads).
+type OrderResponseSchema = components['schemas']['OrderResponse']
+type PhysicalFulfillmentSchema = components['schemas']['PhysicalFulfillmentResponse']
+type DigitalFulfillmentSchema = components['schemas']['DigitalFulfillmentResponse']
 
 export type { FindOrderParams, CreateOrderParams, OrderStatus }
 
-interface RawOrderItem {
-  id: string
-  product_name?: string
-  productName?: string
-  image?: string
-  quantity?: number
-  unit_price?: number
-  price?: number
+/**
+ * Request body for the real POST /orders/storefront/bespoke atomic checkout
+ * (kasuvia-store-management's BespokeBookingCheckoutRequest). Bespoke
+ * products can never be added to a cart (ErrBespokeNotCartable) — this is
+ * the only real path to a paid bespoke commission from the storefront.
+ */
+export interface CreateBespokeOrderParams {
+  product_id: string
+  brief: string
+  reference_images?: string[]
+  measurements?: Record<string, string>
+  preferred_timeline?: string
+  special_instructions?: string
+  deposit_ratio?: number
+  physical?: {
+    shipping_address: Record<string, unknown>
+  }
+  notes?: string
+  discount_code?: string
+  guest_email?: string
+  guest_name?: string
+  guest_phone?: string
+  checkout_session_id?: string
+}
+
+/**
+ * Request body for the real POST /orders/storefront/service atomic PAID
+ * checkout (kasuvia-store-management's ServiceBookingCheckoutRequest) —
+ * distinct from the free self-service `bookAppointment` flow
+ * (service-booking.service.ts, POST /service/bookings/schedule). Service
+ * products can never be added to a cart (ErrServiceNotCartable) — this is
+ * the only path to a PAID service booking from the storefront.
+ */
+export interface CreateServiceBookingOrderParams {
+  product_id: string
+  scheduled_date: string
+  scheduled_time: string
+  staff_id?: string
+  notes?: string
+  discount_code?: string
+  guest_email?: string
+  guest_name?: string
+  guest_phone?: string
+  checkout_session_id?: string
 }
 
+type RawOrderItem = NonNullable<OrderResponseSchema['items']>[number]
+
 interface RawShippingAddress {
   first_name?: string
   last_name?: string
@@ -32,40 +94,44 @@ interface RawShippingAddress {
   lga?: string
 }
 
-interface RawOrder {
-  id: string
-  display_id?: string
-  items?: RawOrderItem[]
-  total_amount?: number
-  total?: number
-  status: OrderStatus
-  customer_email?: string
-  customer_name?: string
-  guest_email?: string
-  guest_phone?: string
-  guest_name?: string
-  guest_token?: string
-  shipping_address?: RawShippingAddress | string | null
-  delivery_method?: string
-  tracking_number?: string
-  delivery_status?: string
-  carrier_name?: string
-  terminal_shipment_id?: string
-  product_type?: string
-  bespoke_stage?: string
-  bespoke_brief?: string
-  created_at?: string
-  updated_at?: string
-  cancellation_reason?: string
+/**
+ * The real backend response, typed from the generated schema (see the
+ * codegen comment above `OrderResponseSchema`). `status` is narrowed from
+ * the schema's bare `string` (OrderResponse.status has no Literal/Enum on
+ * the backend either — it's genuinely just `str` there) to the SDK's own
+ * real OrderStatus union.
+ *
+ * `cancellation_reason` and `bespoke_stage` are NOT part of this type
+ * (confirmed absent from OrderResponse/PhysicalFulfillmentResponse/
+ * BespokeFulfillmentResponse's real field lists) — see
+ * normaliseStorefrontOrder's own comments on both for what actually backs
+ * (or doesn't back) the public Order type's equivalent fields.
+ */
+// NOTE: deliberately NOT `Omit<OrderResponseSchema, 'status'> & {...}` -
+// OrderResponseSchema is intersected with a string-index signature
+// (`& {[key: string]: unknown}`, from the backend's `extra: "allow"`
+// model_config), and `Omit`'s `Pick<T, Exclude<keyof T, K>>` definition
+// makes `keyof` collapse to just `string` on a type with a string index
+// signature, silently losing every specific field (every property access
+// on the "Omit" result then wrongly resolves to `{}`). A plain
+// intersection avoids `keyof` entirely and works correctly instead.
+type RawOrder = OrderResponseSchema & { status: OrderStatus }
+
+/** The real, non-null shipping_address shape (PhysicalFulfillmentResponse's
+ * own field types as a schemaless `Dict[str, Any]` on the backend, so
+ * openapi-typescript can't infer it beyond "some object" — this is the same
+ * defensive cast the code already did before this fix, just now sourced
+ * from the real nested location). */
+function extractShippingAddress(raw: RawOrder): RawShippingAddress | null {
+  const val = raw.physical_fulfillment?.shipping_address
+  return typeof val === 'object' && val !== null ? val as unknown as RawShippingAddress : null
 }
 
 function deriveCustomerName(raw: RawOrder): string {
   if (raw.customer_name) return raw.customer_name
   if (raw.guest_name) return raw.guest_name
 
-  const addr = typeof raw.shipping_address === 'object' && raw.shipping_address !== null
-    ? raw.shipping_address as RawShippingAddress
-    : null
+  const addr = extractShippingAddress(raw)
   if (addr) {
     const full = `${addr.first_name ?? ''} ${addr.last_name ?? ''}`.trim()
     if (full) return full
@@ -80,33 +146,144 @@ function deriveCustomerName(raw: RawOrder): string {
 function normaliseStorefrontOrder(raw: RawOrder): Order {
   const items: OrderItem[] = (raw.items ?? []).map((item) => ({
     id: item.id,
-    productName: item.product_name ?? item.productName ?? '',
-    image: item.image ?? '',
-    quantity: item.quantity ?? 1,
-    price: item.unit_price ?? item.price ?? 0,
+    order_id: item.order_id,
+    product_id: item.product_id ?? undefined,
+    variant_id: item.variant_id ?? undefined,
+    product_name: item.product_name ?? '',
+    quantity: item.quantity,
+    unit_price: item.unit_price,
+    variant_details: item.variant_details as Record<string, unknown> | undefined,
+    custom_measurements: item.custom_measurements as Record<string, unknown> | undefined,
+    image_url: item.image_url ?? undefined,
   }))
 
-  const addr = typeof raw.shipping_address === 'object' && raw.shipping_address !== null
-    ? raw.shipping_address as RawShippingAddress
-    : null
+  const addr = extractShippingAddress(raw)
+
+  const customerName = deriveCustomerName(raw)
+  const customerEmail = raw.guest_email ?? raw.customer_email ?? ''
+  const physical = raw.physical_fulfillment
+
+  // No silent fallback: an order's currency determines what a subsequent
+  // payment actually gets charged in. A missing value here means the backend
+  // response is malformed — defaulting to a guessed currency would make the
+  // failure invisible until money changes hands in the wrong currency
+  // (see plan: Order Currency Fix).
+  if (!raw.currency) {
+    throw new Error(`Order ${raw.id} response is missing a currency field.`)
+  }
+  // REAL BUG FIXED (2026-09-22): same class of bug as the currency check
+  // above, previously missed. `created_at`/`updated_at` silently fell back
+  // to `new Date().toISOString()` (right now) when absent — fabricating a
+  // plausible but wrong "placed on" date instead of surfacing a malformed
+  // response. `business_id` silently fell back to `''`.
+  if (!raw.created_at) {
+    throw new Error(`Order ${raw.id} response is missing a created_at field.`)
+  }
+  if (!raw.updated_at) {
+    throw new Error(`Order ${raw.id} response is missing an updated_at field.`)
+  }
+  if (!raw.business_id) {
+    throw new Error(`Order ${raw.id} response is missing a business_id field.`)
+  }
 
   return {
     id: raw.id,
-    display_id: raw.display_id,
+    display_id: raw.display_id || raw.id,
+    business_id: raw.business_id,
+    customer_id: raw.customer_id ?? undefined,
     items,
-    total: raw.total_amount ?? raw.total ?? 0,
     status: raw.status,
-    customerEmail: raw.guest_email ?? raw.customer_email ?? '',
-    customerName: deriveCustomerName(raw),
-    createdAt: raw.created_at ? new Date(raw.created_at).getTime() : Date.now(),
-    updatedAt: raw.updated_at ? new Date(raw.updated_at).getTime() : Date.now(),
-    deliveryMethod: raw.delivery_method,
-    trackingNumber: raw.tracking_number,
-    deliveryAddress: typeof raw.shipping_address === 'string'
-      ? raw.shipping_address
-      : addr
-        ? `${addr.street}, ${addr.city}, ${addr.state}, ${addr.country}`
-        : undefined,
+    payment_status: raw.payment_status || 'pending',
+    product_type: (raw.product_type ?? undefined) as Order['product_type'],
+
+    // Canonical backend fields
+    total_amount: raw.total_amount,
+    currency: raw.currency,
+    subtotal_amount: raw.subtotal_amount ?? undefined,
+    shipping_amount: raw.shipping_amount ?? undefined,
+    discount_amount: raw.discount_amount ?? undefined,
+    tax_amount: raw.tax_amount ?? undefined,
+    customer_name: customerName,
+    customer_email: customerEmail,
+    // REAL BUG FIXED (2026-09-23) via the REST codegen initiative: every
+    // field below this point used to read a flat `raw.<field>` that does
+    // NOT exist anywhere on the real OrderResponse - confirmed by reading
+    // the actual Pydantic classes, not just the generated types. They
+    // genuinely live nested under `physical_fulfillment` (shipping/
+    // tracking/carrier/pickup/surcharge/weight) or `digital_fulfillment`
+    // (buyer_country) - "One nested block per product type, instead of
+    // ~35 flat fields on OrderBase" per that schema file's own Order
+    // Schema Refactor comment. Every one of these was silently `undefined`
+    // on every real order: a customer's tracking number, carrier, delivery
+    // status, and shipping address never actually rendered anywhere on the
+    // storefront's order tracking page.
+    tracking_number: physical?.tracking_number ?? undefined,
+    delivery_status: physical?.delivery_status ?? undefined,
+    carrier_name: physical?.carrier_name ?? undefined,
+    carrier_slug: physical?.carrier_slug ?? undefined,
+    terminal_rate_id: physical?.terminal_rate_id ?? undefined,
+    guest_token: raw.guest_token ?? undefined,
+    guest_email: raw.guest_email ?? undefined,
+    guest_phone: raw.guest_phone ?? undefined,
+    guest_name: raw.guest_name ?? undefined,
+    buyer_country: raw.digital_fulfillment?.buyer_country ?? undefined,
+    created_at: raw.created_at,
+    updated_at: raw.updated_at,
+
+    // Weight discrepancy & surcharge fields (Task 2) — physical_fulfillment
+    shipping_surcharge_amount: physical?.shipping_surcharge_amount ?? undefined,
+    shipping_surcharge_reason: physical?.shipping_surcharge_reason ?? undefined,
+    shipping_surcharge_description: physical?.shipping_surcharge_description ?? undefined,
+    shipping_surcharge_applied_at: physical?.shipping_surcharge_applied_at ?? undefined,
+    declared_weight_kg: physical?.declared_weight_kg ?? undefined,
+    actual_weight_kg: physical?.actual_weight_kg ?? undefined,
+
+    // Self-pickup verification fields (Task 3) — physical_fulfillment
+    pickup_verification_code: physical?.pickup_verification_code ?? undefined,
+    pickup_verification_code_generated_at: physical?.pickup_verification_code_generated_at ?? undefined,
+    pickup_verification_code_used_at: physical?.pickup_verification_code_used_at ?? undefined,
+    pickup_verification_failed_attempts: physical?.pickup_verification_failed_attempts,
+    pickup_verification_locked_until: physical?.pickup_verification_locked_until ?? undefined,
+    pickup_qr_payload: physical?.pickup_qr_payload ?? undefined,
+
+    // Bespoke fields — real backend nests these under `bespoke_fulfillment`.
+    bespoke_brief: raw.bespoke_fulfillment?.brief ?? undefined,
+    bespoke_reference_images: raw.bespoke_fulfillment?.reference_images ?? undefined,
+    bespoke_measurements: raw.bespoke_fulfillment?.measurements ?? undefined,
+    bespoke_preferred_timeline: raw.bespoke_fulfillment?.preferred_timeline ?? undefined,
+    bespoke_special_instructions: raw.bespoke_fulfillment?.special_instructions ?? undefined,
+    bespoke_deposit_ratio: raw.bespoke_fulfillment?.deposit_ratio ?? undefined,
+    bespoke_deposit_amount: raw.bespoke_fulfillment?.deposit_amount ?? undefined,
+    bespoke_balance_amount: raw.bespoke_fulfillment?.balance_amount ?? undefined,
+    bespoke_status: raw.bespoke_fulfillment?.status ?? undefined,
+    bespoke_deliverable_submitted_at: raw.bespoke_fulfillment?.deliverable_submitted_at ?? undefined,
+    bespoke_deliverable_url: raw.bespoke_fulfillment?.deliverable_url ?? undefined,
+    bespoke_deliverable_notes: raw.bespoke_fulfillment?.deliverable_notes ?? undefined,
+    bespoke_buyer_approved_at: raw.bespoke_fulfillment?.buyer_approved_at ?? undefined,
+    bespoke_revision_count: raw.bespoke_fulfillment?.revision_count ?? 0,
+    bespoke_revision_notes: raw.bespoke_fulfillment?.revision_notes ?? undefined,
+
+    // SDK camelCase convenience aliases
+    total: raw.total_amount ?? undefined,
+    shippingAmount: raw.shipping_amount ?? undefined,
+    discountAmount: raw.discount_amount ?? undefined,
+    customerEmail: customerEmail,
+    customerName: customerName,
+    createdAt: new Date(raw.created_at).getTime(),
+    updatedAt: new Date(raw.updated_at).getTime(),
+    // REAL BUG FIXED (2026-09-23), found alongside the nesting bug above:
+    // `deliveryMethod` reads physical_fulfillment.shipping_method now
+    // (was reading a flat `delivery_method` field that never existed at
+    // all, anywhere - not even nested). The real value is "carrier" or
+    // "self_pickup" (PhysicalFulfillmentCreate.shipping_method's own
+    // docstring) - see the matching fix in kasuvia-storefront's
+    // OrderDeliveryInfo.tsx, which used to compare against the wrong
+    // string "pickup".
+    deliveryMethod: physical?.shipping_method ?? undefined,
+    trackingNumber: physical?.tracking_number ?? undefined,
+    deliveryAddress: addr
+      ? `${addr.street}, ${addr.city}, ${addr.state}, ${addr.country}`
+      : undefined,
     shippingAddress: addr
       ? {
           first_name: addr.first_name ?? '',
@@ -115,67 +292,124 @@ function normaliseStorefrontOrder(raw: RawOrder): Order {
           street: addr.street ?? '',
           city: addr.city ?? '',
           state: addr.state ?? '',
-          lga: addr.lga ?? '',
+          lga: addr.lga,
           country: addr.country ?? '',
-          postal: addr.postal ?? '',
+          postal: addr.postal,
         }
       : undefined,
-    cancellationReason: raw.cancellation_reason,
+    // REAL GAP (2026-09-23), NOT fixed here: confirmed cancellation_reason
+    // does not exist anywhere in OrderResponse or any of its fulfillment
+    // sub-schemas (kasuvia-store-management's app/schemas/order.py) - the
+    // cancel-order endpoint accepts a `reason` in its request body but the
+    // backend never persists/returns it back on the order. Permanently
+    // undefined until the backend adds real storage for it; kept as a
+    // field on the public Order type rather than silently removed, since
+    // deleting a public SDK field is a breaking change this fix's scope
+    // doesn't cover.
+    cancellationReason: undefined,
     hasBespoke: raw.product_type === 'bespoke',
-    bespokeStage: raw.bespoke_stage as Order['bespokeStage'],
-    bespokeBrief: raw.bespoke_brief,
-    deliveryStatus: raw.delivery_status,
-    carrierName: raw.carrier_name,
-    terminalShipmentId: raw.terminal_shipment_id,
-    guestToken: raw.guest_token,
-    guestEmail: raw.guest_email,
-    guestPhone: raw.guest_phone,
-    guestName: raw.guest_name,
+    // REAL GAP (2026-09-23), NOT fixed here: same as cancellationReason -
+    // confirmed no `bespoke_stage` field exists anywhere; the real,
+    // equivalent concept is bespoke_fulfillment.status (already exposed
+    // above as `bespoke_status`). Reads that here rather than staying
+    // permanently undefined, since it's genuinely the same real data the
+    // consuming components (BespokeProgress) want to key off of.
+    bespokeStage: raw.bespoke_fulfillment?.status ?? undefined,
+    bespokeBrief: raw.bespoke_fulfillment?.brief ?? undefined,
+    deliveryStatus: physical?.delivery_status ?? undefined,
+    carrierName: physical?.carrier_name ?? undefined,
+    terminalShipmentId: physical?.terminal_shipment_id ?? undefined,
+    guestToken: raw.guest_token ?? undefined,
+    guestEmail: raw.guest_email ?? undefined,
+    guestPhone: raw.guest_phone ?? undefined,
+    guestName: raw.guest_name ?? undefined,
   }
 }
 
-export async function createOrder(config: SdkConfig, accessToken: string, payload: CreateOrderParams): Promise<Order> {
-  const response = await fetch(`${config.backendUrls.store}/orders/storefront`, {
+/**
+ * REAL BUG FIXED (2026-09-22): `accessToken` was mandatory (`string`, not
+ * optional) — the real backend endpoint (`POST /orders/storefront`,
+ * create_storefront_order) explicitly supports guest checkout: `if not
+ * user_id and not x_guest_session: raise 401`, matching the same
+ * X-Guest-Session pattern cart.service.ts already uses. This endpoint
+ * redeems the customer's real server-side cart (guest or authenticated) —
+ * `payload.items`/`payload.product_type` are ignored by the backend
+ * entirely regardless (see CreateOrderParams' own doc comment) — so a
+ * guest with items already in their guest cart had no way to check out at
+ * all through this SDK, even though the backend was built for exactly
+ * that. `guestSessionId` is a separate parameter (not a body field) since
+ * the backend reads it as a header, not JSON.
+ */
+export async function createOrder(
+  config: SdkConfig,
+  accessToken: string | undefined,
+  payload: CreateOrderParams,
+  guestSessionId?: string
+): Promise<Order> {
+  const headers: Record<string, string> = { ...JSON_HEADERS, ...storefrontHeaders(config) }
+  if (accessToken) {
+    headers['Authorization'] = `Bearer ${accessToken}`
+  } else if (guestSessionId) {
+    headers['X-Guest-Session'] = guestSessionId
+  }
+  const data = await apiRequest<RawOrder>(`${config.backendUrls.store}/orders/storefront`, {
     method: 'POST',
-    headers: { 
-      'Content-Type': 'application/json',
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+    headers,
     body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to create order',
   })
-  if (!response.ok) throw new Error('Failed to create order')
-  const data = await response.json()
   return normaliseStorefrontOrder(data)
 }
 
-export async function findOrder(config: SdkConfig, params: FindOrderParams & { guest_token?: string }): Promise<Order> {
-  const queryParams = new URLSearchParams()
-  if (params.email) queryParams.set('email', params.email)
-  if (params.order_id) queryParams.set('order_id', params.order_id)
-  if (params.guest_token) queryParams.set('guest_token', params.guest_token)
-  
-  const response = await fetch(`${config.backendUrls.store}/orders/find/?${queryParams.toString()}`, {
-    headers: { 
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+/** Atomic, cart-less bespoke commission checkout — POST /orders/storefront/bespoke. */
+export async function createBespokeOrder(config: SdkConfig, accessToken: string | undefined, payload: CreateBespokeOrderParams): Promise<Order> {
+  const headers: Record<string, string> = { ...JSON_HEADERS, ...storefrontHeaders(config) }
+  if (accessToken) headers["Authorization"] = `Bearer ${accessToken}`
+
+  const data = await apiRequest<RawOrder>(`${config.backendUrls.store}/orders/storefront/bespoke`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to create bespoke order',
+  })
+  return normaliseStorefrontOrder(data)
+}
+
+/** Atomic, cart-less PAID service booking checkout — POST /orders/storefront/service. */
+export async function createServiceBookingOrder(config: SdkConfig, accessToken: string | undefined, payload: CreateServiceBookingOrderParams): Promise<Order> {
+  const headers: Record<string, string> = { ...JSON_HEADERS, ...storefrontHeaders(config) }
+  if (accessToken) headers["Authorization"] = `Bearer ${accessToken}`
+
+  const data = await apiRequest<RawOrder>(`${config.backendUrls.store}/orders/storefront/service`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(payload),
+    fallbackErrorMessage: 'Failed to create service booking order',
   })
-  if (!response.ok) throw new Error('Failed to find order')
-  const data = await response.json()
   return normaliseStorefrontOrder(data)
 }
 
-export async function findOrderByToken(config: SdkConfig, token: string): Promise<Order> {
-  const response = await fetch(`${config.backendUrls.store}/orders/find/?guest_token=${token}`, {
-    headers: { 
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+/**
+ * REAL BUG FIXED (2026-09-22): called `GET /orders/find/?email=...&order_id=
+ * ...&guest_token=...` — this route does not exist anywhere on the real
+ * backend (confirmed against every route in app/api/v1/endpoints/sales/
+ * orders.py). Every real call 404'd — the entire "track my order by email +
+ * order ID" flow (`/track-order`, the actual page kasuvia-storefront's own
+ * checkout confirmation links to) has been broken. The real, working
+ * mechanism is `POST /orders/track` with a `GuestTrackRequest` body
+ * (`{order_id, email}` — both required, no `guest_token` field exists on
+ * this or any other real request shape). Fixed to match.
+ */
+export async function findOrder(config: SdkConfig, params: FindOrderParams): Promise<Order> {
+  if (!params.email || !params.order_id) {
+    throw new Error('Both email and order_id are required to find an order.')
+  }
+  const data = await apiRequest<RawOrder>(`${config.backendUrls.store}/orders/track`, {
+    method: 'POST',
+    headers: { ...JSON_HEADERS, ...storefrontHeaders(config) },
+    body: JSON.stringify({ order_id: params.order_id, email: params.email }),
+    fallbackErrorMessage: 'Failed to find order',
   })
-  if (!response.ok) throw new Error('Failed to find order by token')
-  const data = await response.json()
   return normaliseStorefrontOrder(data)
 }
 
@@ -184,45 +418,182 @@ export async function getOrders(config: SdkConfig, accessToken: string, params?:
   if (params?.email) queryParams.set('email', params.email)
   if (params?.page) queryParams.set('page', params.page.toString())
   if (params?.page_size) queryParams.set('page_size', params.page_size.toString())
-  
-  const response = await fetch(`${config.backendUrls.store}/orders/?${queryParams.toString()}`, {
-    headers: { 
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+
+  const data = await apiRequest<RawOrder[] | { items: RawOrder[] }>(`${config.backendUrls.store}/orders/?${queryParams.toString()}`, {
+    headers: authHeaders(config, accessToken),
+    fallbackErrorMessage: 'Failed to get orders',
   })
-  if (!response.ok) throw new Error('Failed to get orders')
-  const data = await response.json()
   const items: RawOrder[] = Array.isArray(data) ? data : (data.items ?? [])
   return items.map(normaliseStorefrontOrder)
 }
 
 export async function cancelOrder(config: SdkConfig, accessToken: string, orderId: string, reason: string): Promise<Order> {
-  const response = await fetch(`${config.backendUrls.store}/orders/${orderId}/cancel/`, {
+  const data = await apiRequest<RawOrder>(`${config.backendUrls.store}/orders/${orderId}/cancel/`, {
     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({ reason }),
+    fallbackErrorMessage: 'Failed to cancel order',
   })
-  if (!response.ok) throw new Error('Failed to cancel order')
-  const data = await response.json()
   return normaliseStorefrontOrder(data)
 }
 
-export async function trackOrder(config: SdkConfig, orderId: string, token?: string): Promise<Order> {
-  const queryParams = token ? `?token=${token}` : ''
-  const response = await fetch(`${config.backendUrls.store}/orders/track/${orderId}${queryParams}`, {
-    headers: { 
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+/**
+ * REAL BUG FIXED (2026-09-22): called `GET /orders/track/{orderId}?token=
+ * ...` — this route does not exist on the real backend at all (confirmed
+ * against every route in orders.py). The `token` query param has no
+ * corresponding capability anywhere: the real single-order lookup (`GET
+ * /{order_id}`) requires a genuine authenticated JWT
+ * (`Depends(get_current_user_claims)`) and grants access only to the
+ * order's own customer (matching customer_id, or matching guest_email
+ * against the JWT's email for a guest-checkout order that later registered)
+ * — it has no anonymous/guest-token path at all. There is no real backend
+ * capability today for "look up one order by ID + a standalone token, no
+ * login required" — the only real guest lookup is findOrder (email +
+ * order_id via POST /orders/track, a different, plural-sounding but
+ * distinct endpoint). Fixed to call the real endpoint with its real,
+ * mandatory-JWT contract; the fictional guest-token parameter is removed
+ * rather than kept as a parameter that can never do anything.
+ */
+export async function trackOrder(config: SdkConfig, orderId: string, accessToken: string): Promise<Order> {
+  const data = await apiRequest<RawOrder>(`${config.backendUrls.store}/orders/${orderId}`, {
+    headers: authHeaders(config, accessToken),
+    fallbackErrorMessage: 'Failed to track order',
   })
-  if (!response.ok) throw new Error('Failed to track order')
-  const data = await response.json()
   return normaliseStorefrontOrder(data)
 }
+
+export interface PromoValidationResult {
+  valid: boolean;
+  discount_amount: number;
+  discount_type: 'percentage' | 'fixed';
+  message: string;
+}
+
+/**
+ * Validate a promo / discount code against kasuvia-store-management.
+ *
+ * Routes directly to POST /sales/discounts/validate on the store backend
+ * using X-Storefront-Key + X-Business-ID for tenant isolation.
+ * The backend is the single source of truth for discount validity,
+ * amount calculation, and usage tracking.
+ */
+export async function validatePromoCode(
+  config: SdkConfig,
+  code: string,
+  cartTotal: number,
+): Promise<PromoValidationResult> {
+  try {
+    return await apiRequest<PromoValidationResult>(`${config.backendUrls.store}/sales/discounts/validate`, {
+      method: 'POST',
+      headers: { ...JSON_HEADERS, ...storefrontHeaders(config) },
+      body: JSON.stringify({ code, cart_total: cartTotal }),
+      fallbackErrorMessage: 'Invalid promo code',
+    })
+  } catch (err) {
+    const message = err instanceof ApiError ? err.message : 'Invalid promo code'
+    return { valid: false, discount_amount: 0, discount_type: 'fixed', message }
+  }
+}
+
+// ── Digital download delivery ───────────────────────────────────────────────
+// REAL GAP FIXED (2026-09-22): GET /orders/{order_id}/download/{token} (the
+// exact link every "your download is ready" email sends) had ZERO kasuvia-sdk
+// coverage - the raw backend URL was embedded directly in the email instead,
+// and for a 2+-file product the route returns a raw JSON listing with no
+// page anywhere to render it (a customer clicking "Download" would see raw
+// JSON text in their browser). These are server-only functions (real,
+// un-proxied config.backendUrls.store, like legal.service.ts) meant to be
+// called from a storefront Server Component, never client-side - the real
+// backend route itself needs no business/storefront headers at all (the
+// token IS the capability, by design - see the route's own doc comment),
+// so no config beyond backendUrls.store is required either.
+//
+// Single file: the real route does an HTTP redirect straight to a freshly
+// presigned R2 URL - `redirect: 'manual'` lets a server-side fetch read
+// that Location header directly instead of the runtime silently following
+// it (which would otherwise download the whole file server-side for no
+// reason). 2+ files: the real route returns JSON instead, since a redirect
+// can only ever point at one destination.
+
+export interface DigitalDownloadRedirect {
+  type: 'redirect'
+  url: string
+}
+
+export interface DigitalDownloadFileEntry {
+  id: string
+  display_name: string
+  sort_order: number
+  /** Raw backend URL - never render this directly; resolve it via resolveDigitalDownloadFile instead. */
+  download_url: string
+}
+
+export interface DigitalDownloadListing {
+  type: 'listing'
+  order_id: string
+  product_name: string
+  download_count: number
+  max_downloads: number
+  expires_at: string | null
+  files: DigitalDownloadFileEntry[]
+}
+
+export type DigitalDownloadResult = DigitalDownloadRedirect | DigitalDownloadListing
+
+async function resolveRedirectOrJson<T>(url: string, fallbackErrorMessage: string): Promise<{ type: 'redirect'; url: string } | { type: 'json'; data: T }> {
+  const response = await fetch(url, { redirect: 'manual' })
+
+  if (response.status >= 300 && response.status < 400) {
+    const location = response.headers.get('location')
+    if (!location) {
+      throw new Error(`${fallbackErrorMessage}: server redirected with no destination URL.`)
+    }
+    return { type: 'redirect', url: location }
+  }
+
+  const body = await response.json().catch(() => ({}))
+  if (!response.ok) {
+    throw new ApiError(extractDigitalDownloadError(body, fallbackErrorMessage), response.status, body)
+  }
+  return { type: 'json', data: body as T }
+}
+
+function extractDigitalDownloadError(body: unknown, fallback: string): string {
+  if (typeof body === 'object' && body !== null && 'detail' in body && typeof (body as { detail?: unknown }).detail === 'string') {
+    return (body as { detail: string }).detail
+  }
+  return fallback
+}
+
+/** GET /orders/{order_id}/download/{token} - server-only, no config beyond backendUrls.store needed. */
+export async function resolveDigitalDownload(
+  config: Pick<SdkConfig, 'backendUrls'>,
+  orderId: string,
+  token: string
+): Promise<DigitalDownloadResult> {
+  const result = await resolveRedirectOrJson<Omit<DigitalDownloadListing, 'type'>>(
+    `${config.backendUrls.store}/orders/${orderId}/download/${token}`,
+    'Failed to resolve digital download link'
+  )
+  if (result.type === 'redirect') return result
+  return { type: 'listing', ...result.data }
+}
+
+/** GET /orders/{order_id}/download/{token}/{file_id} - resolves ONE file's real, freshly-presigned URL. */
+export async function resolveDigitalDownloadFile(
+  config: Pick<SdkConfig, 'backendUrls'>,
+  orderId: string,
+  token: string,
+  fileId: string
+): Promise<string> {
+  const result = await resolveRedirectOrJson<never>(
+    `${config.backendUrls.store}/orders/${orderId}/download/${token}/${fileId}`,
+    'Failed to resolve this file\'s download link'
+  )
+  if (result.type !== 'redirect') {
+    throw new Error('Failed to resolve this file\'s download link: server did not return a redirect.')
+  }
+  return result.url
+}
+
+