@kasuvia/sdk 0.0.1

package/src/types/services/index.ts

@@ -0,0 +1,80 @@
+/**
+ * Service booking types for customer-facing storefront
+ */
+
+export type ServiceLocationType = "remote" | "physical" | "both";
+export type ServiceType = "appointment" | "project" | "recurring";
+
+export type AppointmentStatus =
+  | "pending"
+  | "confirmed"
+  | "in_progress"
+  | "completed"
+  | "voided"
+  | "no_show";
+
+export interface AvailableSlot {
+  date: string;
+  start_time: string;
+  end_time: string;
+  slots_remaining: number;
+}
+
+export interface ServiceAppointment {
+  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: ServiceLocationType;
+  customer_address: Record<string, unknown> | null;
+  meeting_link: string | null;
+  customer_notes: string | null;
+  price: number;
+  created_at: string;
+  updated_at: string;
+  completed_at: string | null;
+  voided_at: string | null;
+  cancellation_reason: string | null;
+}
+
+export interface ServiceAppointmentCreatePayload {
+  product_id: string;
+  scheduled_date: string;
+  scheduled_time: string;
+  location_type?: ServiceLocationType;
+  customer_address?: Record<string, unknown>;
+  customer_notes?: string;
+}
+
+export interface DeliverableStatus {
+  pending: "pending";
+  in_progress: "in_progress";
+  review: "review";
+  approved: "approved";
+  rejected: "rejected";
+}
+
+export type DeliverableStatusType = DeliverableStatus[keyof DeliverableStatus];
+
+export interface ServiceDeliverable {
+  id: string;
+  order_id: string;
+  title: string;
+  description: string;
+  status: DeliverableStatusType;
+  due_date: string | null;
+  submitted_at: string | null;
+  attachments: string[];
+  customer_feedback: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface DeliverableApprovalPayload {
+  approved: boolean;
+  feedback?: string;
+}

package/src/types/store/index.ts

@@ -0,0 +1,282 @@
+import { DeliveryAddress } from "./shipping";
+
+export type ProductType = "physical" | "digital" | "service" | "bespoke";
+
+export type { DeliveryAddress } from "./shipping";
+
+export interface Address {
+  street: string
+  city: string
+  state: string
+  country: string
+  zip?: string
+}
+
+export interface Collection {
+  id: string
+  business_id?: string
+  name: string
+  slug: string
+  description?: string
+  image?: { url: string; alt?: string; id?: string }
+  collection_type?: string
+  rules?: Record<string, unknown>
+  status?: string
+  sort_order?: number
+  created_at: string
+  updated_at: string
+}
+
+export interface Inventory {
+  id: string
+  product_id: string
+  variant_id?: string
+  quantity: number
+  reserved: number
+  reorder_point: number
+  reorder_quantity: number
+  track_quantity: boolean
+  allow_backorder: boolean
+  available: number
+  is_in_stock: boolean
+  is_low_stock: boolean
+  updated_at: string
+}
+
+export interface ProductVariant {
+  id: string
+  product_id: string
+  sku?: string
+  attributes: Record<string, string>
+  price?: number
+  images: Array<{ url: string; alt?: string; id?: string }>
+  weight_kg?: 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
+}
+
+export interface Product {
+  id: string
+  business_id: string
+  name: string
+  slug: string
+  description?: string
+  brand?: string
+  product_type: ProductType
+  requires_shipping: boolean
+  is_consumable: boolean
+  is_bespoke: boolean
+  base_price: number
+  currency: string
+  images: Array<{ url: string; alt?: string; id?: string }>
+  tags: string[]
+  custom_fields: CustomField[]
+  is_published: boolean
+  is_featured: boolean
+  is_popular: boolean
+  is_new: boolean
+  is_temporary: boolean
+  digital_file_key?: string
+  download_limit?: number
+  download_expires_at?: string
+  weight_kg: number
+  length_cm?: number
+  width_cm?: number
+  height_cm?: number
+  created_at: string
+  updated_at: string
+  variants: ProductVariant[]
+  collections: Collection[]
+}
+
+export interface ListParams {
+  page?: number
+  pageSize?: number
+  search?: string
+  ordering?: string
+  collectionSlug?: string
+  excludeProductId?: string
+}
+
+export interface PaginatedResponse<T> {
+  items: T[]
+  total: number
+  page: number
+  page_size: number
+  total_pages: number
+}
+
+// ============================================================================
+// CART TYPES
+// ============================================================================
+
+export interface CartItem {
+  id: string
+  product_id: string
+  product_slug: string
+  product_name: string
+  image?: string
+  variant_id?: string
+  variant_attributes?: string | Record<string, string>
+  unit_price: number
+  quantity: number
+  custom_measurements?: string
+  is_bespoke: boolean
+  created_at: string
+  updated_at: string
+}
+
+export interface CartResponse {
+  items: CartItem[]
+  subtotal: number
+  total: number
+  item_count: number
+  product_type?: string  // "physical", "digital", "bespoke"
+}
+
+// ============================================================================
+// WISHLIST TYPES
+// ============================================================================
+
+export interface WishlistItem {
+  id: string
+  product_id: string
+  notes?: string
+  created_at: string
+  product_name?: string
+  product_slug?: string
+  product_price?: number
+  product_image?: string
+}
+
+export interface WishlistListResponse {
+  items: WishlistItem[]
+  total: number
+  page: number
+  page_size: number
+  total_pages: number
+}
+
+export interface WishlistCheckResponse {
+  in_wishlist: boolean
+}
+
+export type OrderStatus =
+  | 'pending'
+  | 'confirmed'
+  | 'processing'
+  | 'packed'
+  | 'picked_up'
+  | 'in_transit'
+  | 'shipped'
+  | 'delivered'
+  | 'voided'
+  | 'refunded'
+  | 'failed';
+export type BespokeStageKey = "received" | "development" | "finished" | "dispatched";
+
+export interface OrderItem {
+  id: string;
+  productName: string;
+  image: string;
+  quantity: number;
+  price: number;
+}
+
+export interface Order {
+  id: string;
+  display_id?: string;
+  items: OrderItem[];
+  total: number;
+  status: OrderStatus;
+  customerEmail: string;
+  customerName: string;
+  createdAt: number;
+  updatedAt: number;
+  deliveryMethod?: string;
+  trackingNumber?: string;
+  deliveryAddress?: string;
+  shippingAddress?: DeliveryAddress;
+  cancellationReason?: string;
+  hasBespoke?: boolean;
+  bespokeStage?: BespokeStageKey;
+  bespokeBrief?: string;
+  deliveryStatus?: string;
+  carrierName?: string;
+  terminalShipmentId?: string;
+  guestToken?: string;
+  guestEmail?: string;
+  guestPhone?: string;
+  guestName?: string;
+}
+
+// ============================================================================
+// CHECKOUT TYPES
+// ============================================================================
+
+export interface CheckoutCustomer {
+  first_name: string;
+  last_name: string;
+  email: string;
+  phone: string;
+}
+
+export interface ShippingLocation {
+  street: string;
+  city: string;
+  state: string;
+  lga: string;
+  country: string;
+  postal: string;
+}
+
+// ============================================================================
+// ORDER SERVICE PARAMS
+// ============================================================================
+
+export interface FindOrderParams {
+  email: string;
+  order_id: string;
+}
+
+export interface CreateOrderParams {
+  customer_id?: string | null;
+  status?: string;
+  shipping_address?: DeliveryAddress;
+  checkout_session_id?: string;
+  items: Array<{
+    product_id: string;
+    product_name: string;
+    quantity: number;
+    unit_price: number;
+    variant_id?: string;
+    variant_details?: Record<string, unknown>;
+    custom_measurements?: Record<string, unknown>;
+  }>;
+  delivery_method?: string;
+  delivery_address?: string;
+  total?: number;
+  payment_method?: string;
+  shipping_rate_id?: string;
+  guest_token?: string;
+  guest_email?: string;
+  guest_phone?: string;
+  guest_name?: string;
+  product_type?: string;
+  bespoke_brief?: string;
+  bespoke_reference_images?: string[];
+  bespoke_measurements?: Record<string, string>;
+  bespoke_preferred_timeline?: string;
+  bespoke_special_instructions?: string;
+}

package/src/types/store/shipping.ts

@@ -0,0 +1,38 @@
+/**
+ * Shipping and delivery types for the storefront
+ */
+
+export interface ShippingRate {
+    id: string;
+    carrier_name: string;
+    carrier_logo: string;
+    carrier_rate_description: string;
+    carrier_slug: string;
+    amount: number;
+    currency: string;
+    delivery_time: string;
+    delivery_eta: number;
+    pickup_time: string;
+    pickup_eta: number;
+    pickup_available: boolean;
+    dropoff_available?: boolean;
+    dropoff_required?: boolean;
+}
+
+export interface ShippingRatesResponse {
+    status: boolean;
+    message: string;
+    data: ShippingRate[];
+}
+
+export interface DeliveryAddress {
+    first_name: string;
+    last_name: string;
+    phone: string;
+    street: string;
+    city: string;
+    state: string;
+    lga: string;
+    country: string;
+    postal: string;
+}

package/src/types/ui/index.ts

@@ -0,0 +1,32 @@
+export type Theme = "light" | "dark"
+export type LangCode = "en" | "ha" | "yo" | "ig" | "fr"
+
+export interface AppState {
+    theme: Theme
+    lang: LangCode
+    currency: string
+}
+
+export interface AppContextValue extends AppState {
+    setTheme: (t: Theme) => void
+    setLang: (l: LangCode) => void
+    setCurrency: (c: string) => void
+    formatPrice: (amount: number, fromCurrency?: string) => string
+    resetAppState: () => void
+    t: (text: string) => string
+    translate: (text: string) => Promise<string>
+}
+
+export interface Country {
+  name: string
+  code: string
+  dial_code: string
+  min_age: number
+}
+
+export interface State {
+  name: string
+  code: string
+  full_iso_code: string
+  type: string
+}

package/src/utils/cache.ts

@@ -0,0 +1,33 @@
+/**
+ * Cache Tiers Utility
+ * 
+ * Provides cache configuration for React Query based on environment.
+ */
+
+const CACHE_TIERS = {
+  none:     { staleTime: 0,               gcTime: 0                },
+  infinity: { staleTime: Infinity,        gcTime: 0                },
+  low:      { staleTime: 1000 * 30,       gcTime: 1000 * 60        }, // 30s / 1m
+  medium:   { staleTime: 1000 * 60 * 5,   gcTime: 1000 * 60 * 10  }, // 5m / 10m
+  high:     { staleTime: 1000 * 60 * 30,  gcTime: 1000 * 60 * 60  }, // 30m / 1h
+} as const;
+
+export type CacheTier = keyof typeof CACHE_TIERS;
+
+let isDevelopment = true;
+
+/**
+ * Set the environment mode for cache configuration
+ */
+export function setEnvironmentMode(development: boolean): void {
+  isDevelopment = development;
+}
+
+/**
+ * Get cache configuration for a given tier
+ * In development, returns 'none' tier to disable caching
+ */
+export const getCacheTier = (tier: CacheTier) => {
+  if (isDevelopment) return CACHE_TIERS.none;
+  return CACHE_TIERS[tier];
+};

package/src/utils/checkout.ts

@@ -0,0 +1,39 @@
+import { buildFullName } from "./customer";
+import type { CheckoutCustomer, DeliveryAddress, Order, ShippingLocation } from "../types";
+
+export function buildDeliveryAddress(customer: CheckoutCustomer, location: ShippingLocation): DeliveryAddress {
+    return {
+        first_name: customer.first_name,
+        last_name: customer.last_name,
+        phone: customer.phone,
+        ...location,
+    };
+}
+
+export function getCheckoutCustomerName(customer: CheckoutCustomer): string {
+    return buildFullName(customer.first_name, customer.last_name) ?? customer.email.split("@")[0];
+}
+
+export function enrichCompletedOrder(
+    order: Order,
+    options: {
+        customer: CheckoutCustomer;
+        location?: ShippingLocation;
+        bespokeBrief?: string;
+        productType?: "physical" | "digital" | "bespoke" | null;
+    },
+): Order {
+    const customerName = getCheckoutCustomerName(options.customer);
+
+    return {
+        ...order,
+        customerName: order.customerName || customerName,
+        customerEmail: order.customerEmail || options.customer.email,
+        shippingAddress:
+            order.shippingAddress ??
+            (options.productType === "physical" && options.location
+                ? buildDeliveryAddress(options.customer, options.location)
+                : undefined),
+        bespokeBrief: order.bespokeBrief ?? options.bespokeBrief,
+    };
+}

package/src/utils/customer.ts

@@ -0,0 +1,20 @@
+import type { CustomerUser } from "../types";
+
+export function buildFullName(firstname?: string, lastname?: string): string | undefined {
+  const name = [firstname, lastname].filter(Boolean).join(' ').trim()
+  return name || undefined
+}
+
+export function splitFullName(fullName?: string): { firstname: string; lastname: string } {
+  if (!fullName?.trim()) return { firstname: '', lastname: '' }
+  const parts = fullName.trim().split(/\s+/)
+  return {
+    firstname: parts[0] ?? '',
+    lastname: parts.slice(1).join(' '),
+  }
+}
+
+export function getCustomerDisplayName(user: CustomerUser): string {
+  const fromParts = buildFullName(user.firstname, user.lastname)
+  return fromParts || user.full_name || user.email.split('@')[0]
+}

package/src/utils/error-handler.ts

@@ -0,0 +1,14 @@
+import axios from 'axios';
+
+/**
+ * Type-safe way to extract an error message from an API error.
+ */
+export function getErrorMessage(error: unknown, fallback: string = "Something went wrong"): string {
+    if (axios.isAxiosError(error)) {
+        return error.response?.data?.detail || error.response?.data?.message || error.message || fallback;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return fallback;
+}

package/src/utils/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Utils Barrel Export
+ */
+
+export * from './cache'
+export * from './logger'
+export * from './sanitize-url'
+export * from './customer'
+export * from './checkout'
+export * from './error-handler'

package/src/utils/logger.ts

@@ -0,0 +1,79 @@
+/**
+ * Logger Utility
+ * 
+ * Environment-gated logger that suppresses output in production.
+ */
+
+let isDevelopment = true;
+
+/**
+ * Set the environment mode for logging
+ */
+export function setLoggerEnvironmentMode(development: boolean): void {
+  isDevelopment = development;
+}
+
+export const logger = {
+  log: (...args: unknown[]) => {
+    if (isDevelopment) {
+      console.log(...args)
+    }
+  },
+
+  warn: (...args: unknown[]) => {
+    if (isDevelopment) {
+      console.warn(...args)
+    }
+  },
+
+  /**
+   * Logs a warning to the console in development only.
+   * Alias for warn() for Python logging compatibility.
+   * In production, this is a no-op.
+   */
+  warning: (...args: unknown[]) => {
+    if (isDevelopment) {
+      console.warn(...args)
+    }
+  },
+
+  error: (...args: unknown[]) => {
+    if (isDevelopment) {
+      console.error(...args)
+    }
+  },
+
+  info: (...args: unknown[]) => {
+    if (isDevelopment) {
+      console.info(...args)
+    }
+  },
+
+  createScope: (scope: string) => ({
+    log: (...args: unknown[]) => {
+      if (isDevelopment) {
+        console.log(`[${scope}]`, ...args)
+      }
+    },
+    warn: (...args: unknown[]) => {
+      if (isDevelopment) {
+        console.warn(`[${scope}]`, ...args)
+      }
+    },
+    warning: (...args: unknown[]) => {
+      if (isDevelopment) {
+        console.warn(`[${scope}]`, ...args)
+      }
+    },
+    error: (...args: unknown[]) => {
+      if (isDevelopment) {
+        console.error(`[${scope}]`, ...args)
+      }
+    },
+    info: (...args: unknown[]) => {
+      if (isDevelopment) {
+        console.info(`[${scope}]`, ...args)
+      }
+    },
+  }),
+}

package/src/utils/sanitize-url.ts

@@ -0,0 +1,55 @@
+export class InvalidBaseURLError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidBaseURLError";
+  }
+}
+
+const ALLOWED_SCHEMES = new Set(["http:", "https:", "ws:", "wss:"]);
+
+/**
+ * Normalizes a URL by trimming whitespace and stripping trailing slashes.
+ */
+export function sanitizeBaseUrl(
+  url: string | undefined | null,
+  name = "URL"
+): string {
+  if (url == null) {
+    throw new InvalidBaseURLError(`${name} is not set`);
+  }
+
+  const cleaned0 = url.trim();
+  if (!cleaned0) {
+    throw new InvalidBaseURLError(`${name} is empty`);
+  }
+
+  // Strip all trailing slashes
+  const cleaned = cleaned0.replace(/\/+$/, "");
+
+  let parsed: URL;
+  try {
+    parsed = new URL(cleaned);
+  } catch {
+    throw new InvalidBaseURLError(
+      `${name} must start with http://, https://, ws://, or wss://, got: ${url}`
+    );
+  }
+
+  if (!ALLOWED_SCHEMES.has(parsed.protocol)) {
+    throw new InvalidBaseURLError(
+      `${name} must start with http://, https://, ws://, or wss://, got: ${url}`
+    );
+  }
+
+  if (!parsed.hostname) {
+    throw new InvalidBaseURLError(`${name} is missing a host: ${url}`);
+  }
+
+  if (parsed.search || parsed.hash) {
+    throw new InvalidBaseURLError(
+      `${name} should not contain a query or fragment: ${url}`
+    );
+  }
+
+  return cleaned;
+}