@kasuvia/sdk 0.0.8 → 0.0.9

package/src/types/index.ts

@@ -8,9 +8,10 @@
  * - payments: kasuvia-payment-system
  * - cms: kasuvia-cms
  * - media: kasuvia-media-system
- * - consultations: kasuvia-store-management (consultations feature)
+ * - consultations: kasuvia-store-management (real bespoke commission types only — the file's
+ *   name is historical; the fictional "Consultation" resource it used to also hold was removed)
  * - services: kasuvia-store-management (service booking feature)
- * - bespoke: kasuvia-store-management (bespoke slot booking feature)
+ * - reviews: kasuvia-crm (reviews and comments feature)
  * - business: business configuration
  * - ui: UI/app state types
  */
@@ -20,8 +21,9 @@ export * from './store'
 export * from './payments'
 export * from './consultations'
 export * from './services'
-export * from './bespoke'
+export * from './reviews'
 export * from './cms'
+export * from './cms/legal'
 export * from './media'
 export * from './business'
 export * from './ui'

package/src/types/media/index.ts

@@ -1,7 +1,39 @@
 /**
  * Media types for the storefront
+ *
+ * Mirrors `Affiliation` in `kasuvia-media-system/app/models/media.py`, the real
+ * source of truth. Re-synced 2026-09-04 (media affiliation recheck): this mirror
+ * was missing `Business` and `Review` entirely, and wrongly described
+ * `BusinessOwner` as covering logos too.
+ *
+ * Canonical affiliations:
+ * - Content: CMS and website builder content — the ONE shared tag for both
+ * - Product: Product images
+ * - Collection: Collection images
+ * - Chat: AI/customer chat interactions
+ * - Review: photos a customer attaches to a product review (kasuvia-crm) —
+ *   distinct from Customer (a person's own identity photo, not
+ *   customer-GENERATED content)
+ * - Business: a business's own logo
+ * - BusinessOwner: the business owner's OWN personal avatar — distinct from
+ *   Business (the business's logo); never the same asset
+ * - Staff: staff avatars
+ * - Customer: customer avatars
+ * - General: General use cases
  */
 
+export type MediaAffiliation =
+  | 'Content'
+  | 'Product'
+  | 'Collection'
+  | 'Chat'
+  | 'Review'
+  | 'Business'
+  | 'BusinessOwner'
+  | 'Staff'
+  | 'Customer'
+  | 'General'
+
 export interface MediaAsset {
   id: string
   url: string
@@ -9,7 +41,7 @@ export interface MediaAsset {
   content_type: string
   size: number
   business_id: string
-  affiliation: string
+  affiliation: MediaAffiliation
   created_at: string
   alt?: string
   description?: string
@@ -19,7 +51,7 @@ export interface MediaUploadParams {
   business_id?: string
   owner_id?: string
   uploaded_by_name?: string
-  affiliation?: string
+  affiliation?: MediaAffiliation
   context: string  // Required for security: describes the upload context (e.g., product, user, business)
   entity_id: string  // Required for security: ID of the entity this file belongs to
   alt?: string
@@ -30,7 +62,7 @@ export interface MediaUploadParams {
 export interface MediaAssetUpdatePayload {
   alt?: string
   description?: string
-  affiliation?: string
+  affiliation?: MediaAffiliation
 }
 
 export interface StorageStats {

package/src/types/payments/index.ts

@@ -45,26 +45,103 @@ export interface SupportedLanguagesResponse {
   languages: BackendLanguage[];
 }
 
+export enum PaymentGatewayEnum {
+  MONNIFY = "monnify",
+  FLUTTERWAVE = "flutterwave",
+  PAYSTACK = "paystack",
+}
+
+export type PaymentGateway = PaymentGatewayEnum | "monnify" | "flutterwave" | "paystack";
+
+export enum PaymentMethodTypeEnum {
+  CARD = "card",
+  TRANSFER = "transfer",
+  BANK_TRANSFER = "bank_transfer",
+  ACCOUNT = "account",
+  USSD = "ussd",
+}
+
+export type PaymentMethodType = PaymentMethodTypeEnum | "card" | "transfer" | "bank_transfer" | "account" | "ussd";
+
+export interface PaymentMethodOption {
+  method: PaymentMethodType | string;
+  display_name: string;
+  description: string;
+}
+
+export interface GatewayMethods {
+  gateway: PaymentGateway | string;
+  display_name: string;
+  methods: PaymentMethodOption[];
+}
+
+// ── Wallet Types ───────────────────────────────────────────────────────────────
+
+export interface WalletBalanceResponse {
+  balance: number;
+  currency: string;
+}
+
+export interface WalletLedgerEntry {
+  id: string;
+  entry_type: string;
+  amount: number;
+  currency: string;
+  refund_id?: string | null;
+  transaction_id?: string | null;
+  balance_after: number;
+  created_at: string;
+}
+
+export interface WalletLedgerResponse {
+  items: WalletLedgerEntry[];
+  total: number;
+  page: number;
+  page_size: number;
+}
+
+export interface ClaimWalletCreditRequest {
+  claim_token: string;
+}
+
+export interface OutstandingClaimResponse {
+  wallet_id: string;
+  claim_email: string;
+  balance: number;
+  currency: string;
+  created_at: string;
+}
+
 // ── Request Types ─────────────────────────────────────────────────────────────
 
 export interface DVACreateRequest {
   order_id?: string;
-  amount: number;
+  /** Ignored by the backend — the real order total is always charged instead. Only meaningful (and required) if order_id is omitted. */
+  amount?: number;
   customer_email: string;
   customer_name?: string;
   /** Defaults to NGN — DVA is Monnify-only */
   currency?: string;
+  /** Gateway identifier — the backend requires this explicitly, no default */
+  gateway: string;
+  /** Window origin of the storefront */
+  storefront_origin?: string;
   /** Idempotency key to prevent duplicate DVA creation */
   idempotency_key?: string;
 }
 
 export interface PaymentInitiateRequest {
-  amount: number;
-  currency: string;
+  /** Ignored by the backend when order_id is set — the real order total is always charged instead. Required only if order_id is omitted. */
+  amount?: number;
+  currency?: string;
   customer_email: string;
   customer_name?: string;
   order_id?: string;
   quote_id?: string;
+  /** ISO 2-letter country code (defaults to 'NG') */
+  country_code?: string;
+  /** Gateway chosen by customer (e.g., 'monnify', 'flutterwave', 'paystack') — the backend requires this explicitly, no default */
+  gateway: string;
   /** Window origin of the storefront — used as gateway redirect base URL */
   storefront_origin?: string;
   metadata?: Record<string, string | number | boolean>;
@@ -72,19 +149,6 @@ export interface PaymentInitiateRequest {
   idempotency_key?: string;
 }
 
-export interface ConversionQuote {
-  id: string;
-  business_id: string;
-  from_currency: string;
-  to_currency: string;
-  rate: number;
-  original_amount: number;
-  converted_amount: number;
-  is_used: boolean;
-  expires_at: string;
-  created_at: string;
-}
-
 // ── Response Types ─────────────────────────────────────────────────────────────
 
 export interface DVADetails {

package/src/types/reviews/index.ts

@@ -0,0 +1,116 @@
+/**
+ * Review and Comment types for CRM service
+ */
+
+export enum ModerationStatus {
+  PENDING = 'pending',
+  APPROVED = 'approved',
+  REJECTED = 'rejected'
+}
+
+export interface Review {
+  id: string
+  business_id: string
+  product_id: string
+  order_id?: string
+  customer_id: string
+  /** Real field (kasuvia-crm-go's ReviewResponse.customer_name_masked) — the raw customer_id is never exposed to other storefront visitors. */
+  customer_name_masked: string
+  rating: number
+  body: string
+  media: string[]
+  media_ids: string[]
+  verified_purchase: boolean
+  moderation_status: ModerationStatus
+  merchant_reply?: string
+  merchant_reply_at?: string
+  created_at: string
+  edited_at?: string
+  edit_count: number
+}
+
+export interface Comment {
+  id: string
+  business_id: string
+  product_id: string
+  customer_id?: string
+  /** Real field (kasuvia-crm-go's CommentResponse.customer_name_masked). */
+  customer_name_masked: string
+  body: string
+  parent_comment_id?: string
+  moderation_status: ModerationStatus
+  is_merchant_reply: boolean
+  created_at: string
+  updated_at: string
+}
+
+export interface ReviewCreate {
+  product_id: string
+  /** Required: reviews are purchase-verified — must reference a completed order for this product. */
+  order_id: string
+  rating: number
+  body: string
+  /**
+   * `media` (asset URLs) and `media_ids` (the matching MediaAsset ids) must
+   * be two parallel, order-paired arrays of the SAME length — the real
+   * backend (kasuvia-crm-go's validateMediaPairing) 400s otherwise. Omit
+   * both together, or populate both together in the same order.
+   */
+  media?: string[]
+  media_ids?: string[]
+}
+
+export interface ReviewUpdate {
+  rating?: number
+  body?: string
+  /** See ReviewCreate's identical doc comment — media/media_ids must be order-paired, same length. */
+  media?: string[]
+  media_ids?: string[]
+}
+
+export interface CommentCreate {
+  product_id: string
+  body: string
+  parent_comment_id?: string
+}
+
+export interface CommentUpdate {
+  body?: string
+}
+
+export interface MerchantReplyCreate {
+  body: string
+}
+
+export interface ReviewModerationAction {
+  status: ModerationStatus
+  reason?: string
+}
+
+export interface CommentModerationAction {
+  status: ModerationStatus
+  reason?: string
+}
+
+// REAL BUG FIXED (2026-09-21): these used `reviews`/`comments`/`total` —
+// kasuvia-crm-go's real GET /products/{id}/reviews and .../comments
+// (reviews.go) return the platform's standard pagination shape instead
+// (`results`/`count`/`page`/`page_size`/`total_pages`), same convention as
+// every other paginated Kasuvia endpoint.
+export interface ProductReviewsResponse {
+  results: Review[]
+  count: number
+  page: number
+  page_size: number
+  total_pages: number
+  average_rating: number | null
+  rating_distribution: Record<number, number>
+}
+
+export interface ProductCommentsResponse {
+  results: Comment[]
+  count: number
+  page: number
+  page_size: number
+  total_pages: number
+}

package/src/types/services/index.ts

@@ -1,77 +1,152 @@
 /**
- * Service booking types for customer-facing storefront
+ * Service booking types for customer-facing storefront.
+ *
+ * REAL BUG FIXED (2026-09-20): this entire file used to describe a fictional
+ * API shape that never matched kasuvia-store-management's real service-
+ * booking backend (`app/schemas/service.py`, `app/api/v1/endpoints/service/
+ * bookings.py`) — wrong field names (`appointment_date` vs the real
+ * `scheduled_date`), a status enum with values the backend never emits
+ * ("pending" vs the real "scheduled"), fields that don't exist on the real
+ * response (`location_type`, `customer_address`, `meeting_link`, `price`),
+ * and a whole "deliverables" concept (`ServiceDeliverable`,
+ * `DeliverableApprovalPayload`) that has no backend counterpart at all — the
+ * real analogous feature is the milestone/escrow system below, a different
+ * shape entirely. Rebuilt field-for-field against the real Pydantic schemas.
  */
 
-export type AppointmentStatus =
-  | "pending"
+export type ServiceBookingStatus =
+  | "scheduled"
   | "confirmed"
   | "in_progress"
   | "completed"
   | "voided"
   | "no_show";
 
-export interface AvailableSlot {
+/** GET /catalog/products/{product_id}/available-slots response. */
+export interface AvailableSlotsResponse {
+  product_id: string;
   date: string;
-  start_time: string;
-  end_time: string;
-  slots_remaining: number;
+  staff_id: string | null;
+  duration_minutes: number | null;
+  /** false when the business has no/ambiguous location config for this
+   * product — check `reason` for why, `available_slots` is always empty. */
+  serviceable: boolean;
+  reason: string | null;
+  /** ISO time strings (e.g. "14:30:00"), not slot objects. */
+  available_slots: string[];
 }
 
+/** Matches ServiceBookingResponse exactly (kasuvia-store-management/app/schemas/service.py:66-90). */
 export interface ServiceAppointment {
   id: string;
+  business_id: string;
   product_id: string;
   customer_id: string;
   order_id: string | null;
-  status: AppointmentStatus;
-  appointment_date: string;
-  start_time: string;
-  end_time: string;
-  location_type: import("../store").ServiceLocationType;
-  customer_address: Record<string, unknown> | null;
-  meeting_link: string | null;
-  customer_notes: string | null;
-  price: number;
-  created_at: string;
-  updated_at: string;
+  transaction_id: string | null;
+  scheduled_date: string;
+  scheduled_time: string;
+  duration_minutes: number | null;
+  status: ServiceBookingStatus;
+  notes: string | null;
+  reminder_sent: boolean;
+  reminder_scheduled_at: string | null;
+  location_id: string | null;
+  started_at: string | null;
   completed_at: string | null;
+  buyer_confirmed_at: string | null;
+  no_show_at: string | null;
   voided_at: string | null;
   cancellation_reason: string | null;
+  cancellation_window_hours: number;
+  refund_due: boolean | null;
+  refund_processed_at: string | null;
+  is_milestone_based: boolean;
+  assigned_staff_id: string | null;
+  assigned_at: string | null;
+  assignment_method: string | null;
+  created_at: string;
+  updated_at: string;
 }
 
+/** POST /service/bookings/schedule payload (ScheduleServiceRequest). */
 export interface ServiceAppointmentCreatePayload {
   product_id: string;
   scheduled_date: string;
   scheduled_time: string;
-  location_type?: import("../store").ServiceLocationType;
-  customer_address?: Record<string, unknown>;
-  customer_notes?: string;
+  notes?: string;
+  staff_id?: string;
+  /** Required when the product is service_location_type='at_business' and the business runs more than one active location (see useAvailableSlots/logisticsService.listBusinessLocations). */
+  location_id?: string;
 }
 
-export interface DeliverableStatus {
-  pending: "pending";
-  in_progress: "in_progress";
-  review: "review";
-  approved: "approved";
-  rejected: "rejected";
+/** POST /service/bookings/{id}/cancel payload (CustomerCancelBookingRequest). */
+export interface CancelAppointmentPayload {
+  reason?: string;
 }
 
-export type DeliverableStatusType = DeliverableStatus[keyof DeliverableStatus];
+/** POST /service/bookings/{id}/reschedule payload (CustomerRescheduleBookingRequest). */
+export interface RescheduleAppointmentPayload {
+  scheduled_date: string;
+  scheduled_time: string;
+  staff_id?: string;
+}
+
+/** POST /service/bookings/{id}/dispute payload (CustomerOpenDisputeRequest). */
+export interface DisputeAppointmentPayload {
+  reason: string;
+}
+
+/** POST /service/bookings/{id}/confirm payload (BuyerConfirmRequest). */
+export interface ConfirmAppointmentPayload {
+  notes?: string;
+}
+
+export type MilestoneStatus =
+  | "pending"
+  | "funded"
+  | "submitted"
+  | "approved"
+  | "released"
+  | "disputed"
+  | "refunded";
 
-export interface ServiceDeliverable {
+/** Matches ServiceMilestoneResponse + its ServiceMilestoneBase parent
+ * (kasuvia-store-management/app/schemas/service.py:169-173,208-222). */
+export interface ServiceMilestone {
   id: string;
-  order_id: string;
+  booking_id: string;
   title: string;
-  description: string;
-  status: DeliverableStatusType;
-  due_date: string | null;
+  description: string | null;
+  /**
+   * Milestone amount in the order currency.
+   *
+   * REAL BUG FIXED (2026-09-23) via the REST codegen initiative: this was
+   * typed `number`, but the real backend field (ServiceMilestoneBase.amount,
+   * kasuvia-store-management's app/schemas/service.py) is a Pydantic
+   * `Decimal`, which serializes to JSON as a STRING (e.g. "150000.00"), not
+   * a number - confirmed against the generated OpenAPI schema
+   * (`ServiceMilestoneResponse.amount: string`). The one real consumer
+   * (ProjectDeliverables.tsx) called `.toLocaleString()` directly on it,
+   * which on a string just returns the string unchanged (no thousands
+   * separators) rather than the number-formatted value it looked like it
+   * was producing for any amount under 4 digits.
+   */
+  amount: string;
+  sequence: number;
+  status: MilestoneStatus;
+  funded_at: string | null;
   submitted_at: string | null;
-  attachments: string[];
-  customer_feedback: string | null;
+  approved_at: string | null;
+  completion_event_at: string | null;
+  released_at: string | null;
+  dispute_reason: string | null;
+  transaction_id: string | null;
   created_at: string;
   updated_at: string;
 }
 
-export interface DeliverableApprovalPayload {
-  approved: boolean;
-  feedback?: string;
+/** POST /service/bookings/{id}/milestones/{milestone_id}/approve payload. */
+export interface ApproveMilestonePayload {
+  notes?: string;
 }

package/src/types/store/checkout.ts

@@ -0,0 +1,53 @@
+/**
+ * Checkout Session Types
+ *
+ * Mirrors kasuvia-cart-management's public CheckoutSessionResponse shape
+ * (internal/models/checkout_session.go → ToResponse()).
+ * NEVER include internal fields (cart_key, reservation_id, customer_id,
+ * business_id) — those are stripped by ToResponse() and must not appear here.
+ */
+
+/**
+ * One price-locked line in a checkout session.
+ * Matches CheckoutLine in kasuvia-cart-management/internal/models/checkout_session.go.
+ */
+export interface CheckoutLine {
+  cart_item_id: string;
+  product_id: string;
+  variant_id?: string;
+  product_name: string;
+  product_slug: string;
+  image_url?: string;
+  sku: string;
+  quantity: number;
+  /** Price confirmed by store-management at session-creation time — locked for session TTL. */
+  unit_price: number;
+  line_total: number;
+  reserved_units: number;
+  product_type: string;
+}
+
+/**
+ * Public checkout session returned by:
+ *   POST /api/v1/checkout/session
+ *   GET  /api/v1/checkout/session/{session_id}
+ *
+ * Matches CheckoutSessionResponse in kasuvia-cart-management/internal/models/checkout_session.go.
+ * Do NOT use `id` — the backend field is `session_id`.
+ */
+export interface CheckoutSession {
+  session_id: string;
+  items: CheckoutLine[];
+  subtotal: number;
+  shipping_cost: number;
+  discount_amount: number;
+  tax_amount: number;
+  total: number;
+  currency: string;
+  /** Derived from cart lines — "physical" | "digital" | "service" | "bespoke" | "mixed" | null */
+  product_type?: string | null;
+  /** "pending" | "consumed" | "abandoned" */
+  status: 'pending' | 'consumed' | 'abandoned';
+  /** RFC3339 timestamp */
+  expires_at: string;
+}