@kasuvia/sdk 0.0.8 → 0.0.9

package/src/types/store/index.ts

@@ -1,9 +1,18 @@
 import type { DeliveryAddress } from "./shipping";
 
 export * from "./shipping";
+export * from "./invoice";
+export * from "./checkout";
 export type { DeliveryAddress };
 
-export type ProductType = "physical" | "digital" | "service" | "bespoke";
+export enum ProductTypeEnum {
+  PHYSICAL = "physical",
+  DIGITAL = "digital",
+  SERVICE = "service",
+  BESPOKE = "bespoke",
+}
+
+export type ProductType = ProductTypeEnum | "physical" | "digital" | "service" | "bespoke";
 
 export enum ServiceTypeEnum {
   APPOINTMENT = 'appointment',
@@ -13,13 +22,18 @@ export enum ServiceTypeEnum {
 
 export type ServiceType = ServiceTypeEnum | 'appointment' | 'project' | 'recurring'
 
+// REAL BUG FIXED (2026-09-21): these values didn't match anything the real
+// backend ever stores — kasuvia-store-management's Product.service_location_type
+// (app/models/catalog.py) is validated against exactly "remote" |
+// "at_business" | "customer_location". The old "physical"/"both" values
+// would never match a real product's actual value.
 export enum ServiceLocationTypeEnum {
   REMOTE = 'remote',
-  PHYSICAL = 'physical',
-  BOTH = 'both',
+  AT_BUSINESS = 'at_business',
+  CUSTOMER_LOCATION = 'customer_location',
 }
 
-export type ServiceLocationType = ServiceLocationTypeEnum | 'remote' | 'physical' | 'both'
+export type ServiceLocationType = ServiceLocationTypeEnum | 'remote' | 'at_business' | 'customer_location'
 
 export enum ServiceRecurringIntervalEnum {
   WEEKLY = 'weekly',
@@ -43,9 +57,11 @@ export interface Collection {
   name: string
   slug: string
   description?: string
-  image?: string
   collection_type?: string
-  rules?: Record<string, unknown>
+  /** Raw JSON string of smart-collection matching rules (kasuvia-store-management's own evaluation detail, never parsed client-side) — the real backend GraphQL field is a String scalar, not a structured object. */
+  rules?: string
+  image_url?: string
+  image_id?: string
   status?: string
   sort_order?: number
   created_at: string
@@ -62,9 +78,9 @@ export interface Inventory {
   reorder_quantity: number
   track_quantity: boolean
   allow_backorder: boolean
-  available: number
-  is_in_stock: boolean
-  is_low_stock: boolean
+  available?: number
+  is_in_stock?: boolean
+  is_low_stock?: boolean
   updated_at: string
 }
 
@@ -76,33 +92,47 @@ export interface ProductVariant {
   price?: number
   images: string[]
   weight_kg?: number
+  length_cm?: number
+  width_cm?: number
+  height_cm?: number
   is_active: boolean
   inventory?: Inventory
-  created_at: string
-  updated_at: string
 }
 
 export interface CustomField {
   label: string
   unit?: string
   required: boolean
-  type?: string
-  key?: string
-  placeholder?: string
+  /** "text" (free text/number input) or "choice" (customer picks from
+   * `options`) — matches kasuvia-store-management's CustomFieldSchema. */
+  field_type: "text" | "choice"
+  /** Only meaningful when field_type is "choice" - the pick list a
+   * merchant configured. Always [] for a "text" field. */
+  options: string[]
+}
+
+/** One file of a DIGITAL/MIXED product (kasuvia-store-management's ProductDigitalFile) — replaces the old dropped single `digital_file_key` scalar. */
+export interface ProductDigitalFile {
+  id: string
+  file_key: string
+  display_name: string
+  sort_order: number
 }
 
 export interface Product {
   id: string
   business_id: string
   name: string
-  slug: string
+  slug?: string
   description?: string
   brand?: string
   product_type: ProductType
   requires_shipping: boolean
   is_consumable: boolean
   is_bespoke: boolean
-  is_physical?: boolean | null  // For bespoke products: indicates if custom item requires physical delivery
+  is_physical?: boolean
+  is_non_returnable?: boolean
+  deposit_percentage?: number
   base_price: number
   currency: string
   sale_price?: number
@@ -110,42 +140,67 @@ export interface Product {
   sale_end?: string
   images: string[]
   tags: string[]
-  custom_fields: CustomField[]
+  custom_fields?: CustomField[]
   is_published: boolean
   is_featured: boolean
   is_popular: boolean
   is_new: boolean
   is_temporary: boolean
-  digital_file_key?: string
+  /** Real fields (kasuvia-crm's review pipeline syncs into these). */
+  average_rating?: number | null
+  rating_count: number
+  /** "kasuvia" for organic products, a real channel key ("whatsapp", etc.) for channel-imported products. */
+  source_channel: string
+  source_channel_ref_id?: string | null
+  digital_files: ProductDigitalFile[]
   download_limit?: number
   download_expires_at?: string
-  // Service-specific fields
-  service_type?: ServiceType | null
-  service_duration_minutes?: number | null
-  service_location_type?: ServiceLocationType | null
+  service_type?: ServiceType
+  service_duration_minutes?: number
+  service_location_type?: ServiceLocationType
+  /** Only meaningful when service_location_type === "customer_location". */
+  service_coverage_radius_km?: number | null
   service_requires_consultation?: boolean
-  service_max_capacity_per_slot?: number | null
+  service_max_capacity_per_slot?: number
   service_buffer_minutes?: number
   service_is_recurring?: boolean
-  service_recurring_interval?: ServiceRecurringInterval | null
+  service_recurring_interval?: ServiceRecurringInterval
   service_project_based?: boolean
-  weight_kg: number
+  weight_kg?: number
   length_cm?: number
   width_cm?: number
   height_cm?: number
+  variants?: ProductVariant[]
+  collections?: Collection[]
+  inventory?: Inventory
   created_at: string
   updated_at: string
-  variants: ProductVariant[]
-  collections: Collection[]
+}
+
+export interface ProductListResponse {
+  items: Product[]
+  total: number
+  page: number
+  page_size: number
+  total_pages: number
+}
+
+export interface CollectionListResponse {
+  items: Collection[]
+  total: number
+  page: number
+  page_size: number
+  total_pages: number
 }
 
 export interface ListParams {
   page?: number
   pageSize?: number
-  search?: string
-  ordering?: string
   collectionSlug?: string
+  search?: string
   excludeProductId?: string
+  /** One of physical/digital/service/bespoke — omit to browse the whole catalog. */
+  productType?: ProductType
 }
 
 export interface PaginatedResponse<T> {
@@ -165,23 +220,29 @@ export interface CartItem {
   product_id: string
   product_slug: string
   product_name: string
-  image?: string
+  image_url?: string
   variant_id?: string
   variant_attributes?: string | Record<string, string>
   unit_price: number
   quantity: number
   custom_measurements?: string
   is_bespoke: boolean
+  product_type?: ProductType
   created_at: string
   updated_at: string
 }
 
 export interface CartResponse {
+  /**
+   * The Redis cart key returned by kasuvia-cart-management on every cart operation.
+   * Used to correlate a cart with a shipping-rate quote and checkout session.
+   */
+  id?: string
   items: CartItem[]
   subtotal: number
   total: number
   item_count: number
-  product_type?: string  // "physical", "digital", "bespoke"
+  product_type?: ProductType
 }
 
 // ============================================================================
@@ -196,7 +257,17 @@ export interface WishlistItem {
   product_name?: string
   product_slug?: string
   product_price?: number
-  product_image?: string
+  /**
+   * REAL BUG FIXED (2026-09-21): was typed as an object
+   * (`Record<string, unknown> | null`) but the real GraphQL resolver
+   * (kasuvia-store-management's queries.py storefront wishlist query)
+   * returns a plain image URL string — a live consumer's `typeof === 'object'`
+   * check against this field was always false, silently hiding every
+   * wishlist item's image.
+   */
+  product_image?: string | null
+  /** Real field (queries.py's `item.product.currency`) — the SDK's own GET_STOREFRONT_WISHLIST query already fetches it. */
+  currency?: string
 }
 
 export interface WishlistListResponse {
@@ -216,40 +287,111 @@ export type OrderStatus =
   | 'confirmed'
   | 'processing'
   | 'packed'
-  | 'picked_up'
+  | 'picked_up'  // Carrier pickup (for carrier shipping)
+  | 'ready_for_pickup'  // Customer self-pickup: order ready for customer collection
+  | 'picked_up_by_customer'  // Customer self-pickup: customer has collected the order
   | 'in_transit'
   | 'shipped'
   | 'delivered'
   | 'voided'
   | 'refunded'
   | 'failed';
-export type BespokeStageKey = "received" | "development" | "finished" | "dispatched";
 
 export interface OrderItem {
   id: string;
-  productName: string;
-  image: string;
+  order_id?: string;
+  product_id?: string;
+  variant_id?: string;
+  product_name: string;
   quantity: number;
-  price: number;
+  unit_price: number;
+  variant_details?: Record<string, unknown>;
+  custom_measurements?: Record<string, unknown>;
+  image_url?: string;
 }
 
 export interface Order {
   id: string;
-  display_id?: string;
-  items: OrderItem[];
-  total: number;
+  display_id: string;
+  business_id: string;
+  customer_id?: string;
   status: OrderStatus;
-  customerEmail: string;
-  customerName: string;
-  createdAt: number;
-  updatedAt: number;
+  payment_status: string;
+  product_type?: ProductType;
+  subtotal_amount?: number;
+  discount_amount?: number;
+  discount_code?: string;
+  tax_amount?: number;
+  shipping_amount?: number;
+  total_amount: number;
+  currency: string;
+  customer_name?: string;
+  customer_email?: string;
+  carrier_name?: string;
+  carrier_slug?: string;
+  terminal_rate_id?: string;
+  tracking_number?: string;
+  delivery_status?: string;
+  guest_token?: string;
+  guest_email?: string;
+  guest_phone?: string;
+  guest_name?: string;
+
+  // Weight discrepancy & surcharge fields (Task 2)
+  shipping_surcharge_amount?: number;
+  shipping_surcharge_reason?: string;
+  shipping_surcharge_description?: string;
+  shipping_surcharge_applied_at?: string;
+  declared_weight_kg?: number;
+  actual_weight_kg?: number;
+
+  // Self-pickup verification fields (Task 3)
+  pickup_verification_code?: string;
+  pickup_verification_code_generated_at?: string;
+  pickup_verification_code_used_at?: string;
+  pickup_verification_failed_attempts?: number;
+  pickup_verification_locked_until?: string;
+  pickup_qr_payload?: string;
+
+  // Bespoke fields (Batch 4)
+  bespoke_brief?: string;
+  bespoke_reference_images?: string[];
+  bespoke_measurements?: Record<string, unknown>;
+  bespoke_preferred_timeline?: string;
+  bespoke_special_instructions?: string;
+  bespoke_deposit_ratio?: number;
+  bespoke_deposit_amount?: number;
+  bespoke_balance_amount?: number;
+  /** BespokeFulfillmentStatus: "processing" | "awaiting_approval" | "under_review" | "confirmed". */
+  bespoke_status?: string;
+  bespoke_deliverable_submitted_at?: string;
+  bespoke_deliverable_url?: string;
+  bespoke_deliverable_notes?: string;
+  bespoke_buyer_approved_at?: string;
+  bespoke_revision_count?: number;
+  bespoke_revision_notes?: string;
+
+  items: OrderItem[];
+  buyer_country?: string;
+  withdrawal_consent_given_at?: string;
+  created_at: string;
+  updated_at: string;
+
+  // Optional SDK legacy compatibility aliases for existing component consumers
+  total?: number;
+  shippingAmount?: number;
+  discountAmount?: number;
+  customerEmail?: string;
+  customerName?: string;
+  createdAt?: number;
+  updatedAt?: number;
   deliveryMethod?: string;
   trackingNumber?: string;
   deliveryAddress?: string;
   shippingAddress?: DeliveryAddress;
   cancellationReason?: string;
   hasBespoke?: boolean;
-  bespokeStage?: BespokeStageKey;
+  bespokeStage?: string;
   bespokeBrief?: string;
   deliveryStatus?: string;
   carrierName?: string;
@@ -278,6 +420,11 @@ export interface ShippingLocation {
   lga: string;
   country: string;
   postal: string;
+  // Task: Plus Codes + Interactive Map Pin-Drop - Geolocation fields
+  latitude?: number | null;
+  longitude?: number | null;
+  plus_code?: string | null;
+  coordinate_source?: 'pin_drop' | 'plus_code' | 'manual' | null;
 }
 
 // ============================================================================
@@ -289,12 +436,81 @@ export interface FindOrderParams {
   order_id: string;
 }
 
+/**
+ * Mirrors kasuvia-store-management's real PhysicalFulfillmentCreate schema
+ * exactly (app/schemas/order.py) — the ONLY place these fields are actually
+ * read from on OrderCreate. See CreateOrderParams's own doc comment for the
+ * real bug this replaced (they used to be declared flat on CreateOrderParams
+ * itself, which OrderBase's `extra: "allow"` config accepted with no
+ * validation error, then silently discarded — order_in.physical stayed None
+ * regardless of what was sent).
+ */
+export interface CreateOrderPhysicalParams {
+  shipping_address?: DeliveryAddress;
+  shipping_latitude?: number | null;
+  shipping_longitude?: number | null;
+  shipping_plus_code?: string | null;
+  shipping_coordinate_source?: 'pin_drop' | 'plus_code' | 'manual' | null;
+  /**
+   * A quote_id from getShippingRates' per-rate "quote_id" field (carrier
+   * shipments only). Required for any nonzero shipping fee — the backend
+   * reads shipping_amount/terminal_rate_id/carrier_name from this stored
+   * quote. self_pickup orders need one too (a real zero-fee quote, see
+   * logisticsService.getShippingRates' self_pickup branch) — the backend
+   * derives resolved_location_id from it, required for both shipping_method.
+   */
+  shipping_quote_id?: string;
+  /** A ShippingQuoteGroup id when the cart needed splitting across multiple locations — mutually exclusive with shipping_quote_id. */
+  shipping_plan_id?: string;
+  /**
+   * Client-repeated for documentation only — the backend derives the REAL
+   * shipping method from the quote itself (resolved_terminal_rate_id is
+   * None for a self_pickup quote), never trusts this field. Safe to omit.
+   */
+  shipping_method?: 'carrier' | 'self_pickup';
+}
+
+/** Mirrors kasuvia-store-management's real DigitalFulfillmentCreate schema exactly. */
+export interface CreateOrderDigitalParams {
+  /** ISO-3166-1 alpha-2 country code (e.g. "NG"). Required for digital orders — the backend's VAT lookup refuses to guess a tax jurisdiction. */
+  buyer_country?: string;
+  withdrawal_consent_given_at?: string;
+}
+
+/**
+ * REAL BUG FIXED (2026-09-24), live-reported ("digital checkout still does
+ * not work" / the [FlatRateVAT] error persisting even after buyer_country
+ * was correctly collected in the UI): shipping_address, shipping_quote_id,
+ * shipping_latitude/longitude/plus_code/coordinate_source, buyer_country,
+ * withdrawal_consent_given_at, and shipping_rate_id used to be declared
+ * FLAT on this interface. kasuvia-store-management's real OrderCreate
+ * schema never had flat equivalents of any of these — confirmed against
+ * app/schemas/order.py directly - they only ever existed nested under
+ * `physical`/`digital` (see CreateOrderPhysicalParams/
+ * CreateOrderDigitalParams above). OrderBase's `extra: "allow"` config
+ * meant sending them flat produced no validation error at all - Pydantic
+ * silently accepted and discarded them, so order_in.physical/order_in.digital
+ * stayed None regardless of what the checkout form collected. Every real
+ * physical order's shipping_address/quote and every real digital order's
+ * buyer_country has been silently lost this way. shipping_rate_id and
+ * pickup_location_id (also previously flat) never existed on the backend
+ * schema in ANY shape - both removed outright as confirmed-dead.
+ */
 export interface CreateOrderParams {
   customer_id?: string | null;
   status?: string;
-  shipping_address?: DeliveryAddress;
   checkout_session_id?: string;
-  items: Array<{
+  physical?: CreateOrderPhysicalParams;
+  digital?: CreateOrderDigitalParams;
+  /**
+   * Line items for the order.
+   *
+   * @important DASHBOARD-ONLY — For the merchant dashboard path (POST /sales/orders),
+   * these items are used directly. For storefront checkout (POST /orders/storefront),
+   * the backend IGNORES this field entirely and reads items from the customer's
+   * server-side Redis cart instead. Do NOT rely on this field for storefront orders.
+   */
+  items?: Array<{
     product_id: string;
     product_name: string;
     quantity: number;
@@ -303,16 +519,21 @@ export interface CreateOrderParams {
     variant_details?: Record<string, unknown>;
     custom_measurements?: Record<string, unknown>;
   }>;
-  delivery_method?: string;
-  delivery_address?: string;
-  total?: number;
+  subtotal_amount?: number;
+  /** @deprecated Ignored by the backend when discount_code is set (recomputed server-side from the real Discount row); rejected outright if sent without a code. */
+  discount_amount?: number;
+  discount_code?: string;
+  promo_code?: string;
+  /** @deprecated Ignored by the backend — tax is always recomputed server-side from the DB VAT rate for the buyer's country. */
+  tax_amount?: number;
+  /** @deprecated Ignored by the backend for carrier shipments once physical.shipping_quote_id is set; rejected outright if sent nonzero without one. */
+  shipping_amount?: number;
   payment_method?: string;
-  shipping_rate_id?: string;
   guest_token?: string;
   guest_email?: string;
   guest_phone?: string;
   guest_name?: string;
-  product_type?: string;
+  product_type?: ProductType;
   bespoke_brief?: string;
   bespoke_reference_images?: string[];
   bespoke_measurements?: Record<string, string>;

package/src/types/store/invoice.ts

@@ -0,0 +1,31 @@
+/**
+ * Invoice Types for Kasuvia Storefront & SDK
+ */
+
+export interface InvoiceLineItem {
+  product_name: string;
+  quantity: number;
+  unit_price: number;
+  total_price?: number;
+  variant_details?: Record<string, string | number>;
+}
+
+export interface Invoice {
+  id: string;
+  invoice_number: string;
+  status: "paid" | "issued" | "overdue" | "voided" | "cancelled";
+  subtotal_amount: number;
+  tax_amount: number;
+  discount_amount: number;
+  total_amount: number;
+  currency: string;
+  issued_at?: string | null;
+  due_date?: string | null;
+  paid_at?: string | null;
+  payment_link_url?: string | null;
+  customer_name?: string | null;
+  customer_email?: string | null;
+  customer_phone?: string | null;
+  notes_and_terms?: string | null;
+  line_items_snapshot?: InvoiceLineItem[];
+}

package/src/types/store/shipping.ts

@@ -5,7 +5,7 @@
 export interface ShippingRate {
     id: string;
     carrier_name: string;
-    carrier_logo: string;
+    carrier_logo: string | null;
     carrier_rate_description: string;
     carrier_slug: string;
     amount: number;
@@ -17,6 +17,13 @@ export interface ShippingRate {
     pickup_available: boolean;
     dropoff_available?: boolean;
     dropoff_required?: boolean;
+    /**
+     * Persisted, single-use, ~45min-TTL quote id — pass this (not `amount`)
+     * as `shipping_quote_id` at order creation. The backend re-reads the
+     * amount/carrier from the stored quote itself; a client-submitted
+     * shipping amount with no valid quote_id is rejected.
+     */
+    quote_id?: string;
 }
 
 export interface ShippingRatesResponse {
@@ -32,9 +39,14 @@ export interface DeliveryAddress {
     street: string;
     city: string;
     state: string;
-    lga: string;
+    lga?: string;
     country: string;
-    postal: string;
+    postal?: string;
+    // Task: Plus Codes + Interactive Map Pin-Drop - Geolocation fields
+    latitude?: number | null;
+    longitude?: number | null;
+    plus_code?: string | null;
+    coordinate_source?: CoordinateSource;
 }
 
 // ============================================================================
@@ -47,3 +59,72 @@ export interface AddressValidationErrorData {
     cities?: Array<{ name: string; city_id: string; stateCode: string; countryCode: string }>;
     states?: Array<{ name: string; code: string; countryCode: string }>;
 }
+
+// ============================================================================
+// GEOLOCATION TYPES (Task: Plus Codes + Interactive Map Pin-Drop)
+// ============================================================================
+
+export type CoordinateSource = 'pin_drop' | 'plus_code' | 'manual' | null;
+
+export interface GeolocationData {
+    latitude?: number | null;
+    longitude?: number | null;
+    plus_code?: string | null;
+    coordinate_source?: CoordinateSource;
+}
+
+export interface ReverseGeocodeRequest {
+    latitude: number;
+    longitude: number;
+}
+
+export interface ReverseGeocodeResponse {
+    city: string | null;
+    state: string | null;
+    country: string | null;
+    country_code: string | null;
+    display_name: string | null;
+}
+
+export interface PlusCodeDecodeRequest {
+    plus_code: string;
+}
+
+export interface PlusCodeDecodeResponse {
+    latitude: number;
+    longitude: number;
+    latitude_lo: number;
+    longitude_hi: number;
+    plus_code: string;
+}
+
+export interface AddressSuggestion {
+    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 AddressAutocompleteResponse {
+    results: AddressSuggestion[];
+}
+
+export interface ShippingAddressPayload extends GeolocationData {
+    first_name: string;
+    last_name: string;
+    phone: string;
+    address_line1: string;
+    address_line2?: string | null;
+    city: string;
+    state: string;
+    country: string;
+    postal_code?: string | null;
+    is_residential?: boolean;
+}
+

package/src/types/ui/index.ts

@@ -1,4 +1,4 @@
-export type Theme = "light" | "dark"
+export type Theme = "light" | "dark" | "system"
 export type LangCode = "en" | "ha" | "yo" | "ig" | "fr"
 
 export interface AppState {