@kasuvia/sdk 0.0.2 → 0.0.4

package/dist/sdk-context-Cy51kEKT.d.ts

@@ -0,0 +1,565 @@
+import React, { ReactNode } from 'react';
+
+/**
+ * Shipping and delivery types for the storefront
+ */
+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;
+}
+interface ShippingRatesResponse {
+    status: boolean;
+    message: string;
+    data: ShippingRate[];
+}
+interface DeliveryAddress {
+    first_name: string;
+    last_name: string;
+    phone: string;
+    street: string;
+    city: string;
+    state: string;
+    lga: string;
+    country: string;
+    postal: string;
+}
+
+type ProductType = "physical" | "digital" | "service" | "bespoke";
+declare enum ServiceTypeEnum {
+    APPOINTMENT = "appointment",
+    PROJECT = "project",
+    RECURRING = "recurring"
+}
+type ServiceType = ServiceTypeEnum | 'appointment' | 'project' | 'recurring';
+declare enum ServiceLocationTypeEnum {
+    REMOTE = "remote",
+    PHYSICAL = "physical",
+    BOTH = "both"
+}
+type ServiceLocationType = ServiceLocationTypeEnum | 'remote' | 'physical' | 'both';
+declare enum ServiceRecurringIntervalEnum {
+    WEEKLY = "weekly",
+    MONTHLY = "monthly",
+    YEARLY = "yearly"
+}
+type ServiceRecurringInterval = ServiceRecurringIntervalEnum | 'weekly' | 'monthly' | 'yearly' | '';
+interface Address {
+    street: string;
+    city: string;
+    state: string;
+    country: string;
+    zip?: string;
+}
+interface Collection {
+    id: string;
+    business_id?: string;
+    name: string;
+    slug: string;
+    description?: string;
+    image?: string;
+    collection_type?: string;
+    rules?: Record<string, unknown>;
+    status?: string;
+    sort_order?: number;
+    created_at: string;
+    updated_at: string;
+}
+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;
+}
+interface ProductVariant {
+    id: string;
+    product_id: string;
+    sku?: string;
+    attributes: Record<string, string>;
+    price?: number;
+    images: string[];
+    weight_kg?: number;
+    is_active: boolean;
+    inventory?: Inventory;
+    created_at: string;
+    updated_at: string;
+}
+interface CustomField {
+    label: string;
+    unit?: string;
+    required: boolean;
+    type?: string;
+    key?: string;
+    placeholder?: string;
+}
+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;
+    is_physical?: boolean | null;
+    base_price: number;
+    currency: string;
+    sale_price?: number;
+    sale_start?: string;
+    sale_end?: string;
+    images: 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;
+    service_type?: ServiceType | null;
+    service_duration_minutes?: number | null;
+    service_location_type?: ServiceLocationType | null;
+    service_requires_consultation?: boolean;
+    service_max_capacity_per_slot?: number | null;
+    service_buffer_minutes?: number;
+    service_is_recurring?: boolean;
+    service_recurring_interval?: ServiceRecurringInterval | null;
+    service_project_based?: boolean;
+    weight_kg: number;
+    length_cm?: number;
+    width_cm?: number;
+    height_cm?: number;
+    created_at: string;
+    updated_at: string;
+    variants: ProductVariant[];
+    collections: Collection[];
+}
+interface ListParams {
+    page?: number;
+    pageSize?: number;
+    search?: string;
+    ordering?: string;
+    collectionSlug?: string;
+    excludeProductId?: string;
+}
+interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    page_size: number;
+    total_pages: number;
+}
+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;
+}
+interface CartResponse {
+    items: CartItem[];
+    subtotal: number;
+    total: number;
+    item_count: number;
+    product_type?: string;
+}
+interface WishlistItem {
+    id: string;
+    product_id: string;
+    notes?: string;
+    created_at: string;
+    product_name?: string;
+    product_slug?: string;
+    product_price?: number;
+    product_image?: string;
+}
+interface WishlistListResponse {
+    items: WishlistItem[];
+    total: number;
+    page: number;
+    page_size: number;
+    total_pages: number;
+}
+interface WishlistCheckResponse {
+    in_wishlist: boolean;
+}
+type OrderStatus = 'pending' | 'confirmed' | 'processing' | 'packed' | 'picked_up' | 'in_transit' | 'shipped' | 'delivered' | 'voided' | 'refunded' | 'failed';
+type BespokeStageKey = "received" | "development" | "finished" | "dispatched";
+interface OrderItem {
+    id: string;
+    productName: string;
+    image: string;
+    quantity: number;
+    price: number;
+}
+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;
+}
+interface CheckoutCustomer {
+    first_name: string;
+    last_name: string;
+    email: string;
+    phone: string;
+}
+interface ShippingLocation {
+    street: string;
+    city: string;
+    state: string;
+    lga: string;
+    country: string;
+    postal: string;
+}
+interface FindOrderParams {
+    email: string;
+    order_id: string;
+}
+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;
+}
+
+/**
+ * Kasuvia SDK Configuration
+ *
+ * Stateless configuration - no module-scoped state.
+ * All configuration is passed as parameters to SDK functions.
+ *
+ * SECURITY NOTE: Backend URLs should never be exposed to the browser.
+ * They should only be used on the server side or in Next.js API routes.
+ */
+interface SdkConfig {
+    businessId: string;
+    storefrontApiKey: string;
+    backendUrls: {
+        auth: string;
+        store: string;
+        payment: string;
+        notifications: string;
+        cms: string;
+    };
+}
+
+type Theme = "light" | "dark";
+type LangCode = "en" | "ha" | "yo" | "ig" | "fr";
+interface AppState {
+    theme: Theme;
+    lang: LangCode;
+    currency: string;
+}
+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>;
+}
+interface Country {
+    name: string;
+    code: string;
+    dial_code: string;
+    min_age: number;
+}
+interface State {
+    name: string;
+    code: string;
+    full_iso_code: string;
+    type: string;
+}
+
+/**
+ * @file types/payments/index.ts
+ * @description All customer-facing payment types for the Kasuvia Payment System.
+ *
+ * Auth model:
+ *   - X-Storefront-Key  → identifies the business storefront
+ *   - X-Business-ID     → tenant context
+ * No business-owner JWT used here — these are CUSTOMER-facing types.
+ *
+ * Payment flow:
+ *   Customer → Business Owner : Monnify (NGN) | Flutterwave (non-NGN)
+ *   Business Owner → Kasuvia     : Subscription (separate, JWT-auth)
+ *   Kasuvia → Business Owner     : Payout (separate, JWT-auth)
+ */
+interface Currency {
+    code: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+    is_active: boolean;
+}
+interface SupportedCurrenciesResponse {
+    currencies: Currency[];
+}
+interface BackendLanguage {
+    code: string;
+    label: string;
+    flag: string;
+}
+interface SupportedLang {
+    code: string;
+    appCode: string;
+    label: string;
+    native: string;
+    flag: string;
+}
+interface SupportedLanguagesResponse {
+    languages: BackendLanguage[];
+}
+interface DVACreateRequest {
+    order_id?: string;
+    amount: number;
+    customer_email: string;
+    customer_name?: string;
+    /** Defaults to NGN — DVA is Monnify-only */
+    currency?: string;
+    /** Idempotency key to prevent duplicate DVA creation */
+    idempotency_key?: string;
+}
+interface PaymentInitiateRequest {
+    amount: number;
+    currency: string;
+    customer_email: string;
+    customer_name?: string;
+    order_id?: string;
+    quote_id?: string;
+    /** Window origin of the storefront — used as gateway redirect base URL */
+    storefront_origin?: string;
+    metadata?: Record<string, string | number | boolean>;
+    /** Idempotency key to prevent duplicate payment initiation */
+    idempotency_key?: string;
+}
+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;
+}
+interface DVADetails {
+    account_number: string;
+    bank_name: string;
+    account_name: string;
+    reference: string;
+    amount: number;
+    transaction_id: string;
+    expires_at: string;
+}
+interface PaymentInitiateResponse {
+    id: string;
+    gateway_ref: string;
+    gateway: string;
+    status: string;
+    /** Normalised top-level checkout URL for gateway redirect */
+    checkout_url: string;
+}
+interface TransactionVerifyResponse {
+    id: string;
+    status: string;
+    amount: number;
+    currency: string;
+    gateway_ref: string;
+    gateway?: string;
+    order_id?: string;
+    escrow_status?: string;
+    escrow_release_date?: string;
+    metadata_json?: Record<string, unknown>;
+}
+
+/**
+ * CMS Types
+ *
+ * Types for kasuvia-cms integration - dynamic content models and entries
+ */
+interface CmsField {
+    name: string;
+    label: string;
+    type: string;
+    required: boolean;
+    config: Record<string, any>;
+    sub_fields?: CmsField[];
+}
+interface CmsModelPermissions {
+    read: boolean;
+    create: boolean;
+    update: boolean;
+    delete: boolean;
+}
+interface CmsModelPublicApiPermissions {
+    public_api: CmsModelPermissions;
+}
+interface CmsModel {
+    id: string;
+    business_id: string;
+    model_slug: string;
+    display_name: string;
+    description: string | null;
+    fields: CmsField[];
+    permissions: CmsModelPublicApiPermissions;
+}
+interface CmsEntry {
+    id: string;
+    business_id: string;
+    model_slug: string;
+    data: Record<string, any>;
+    created_at: string;
+    updated_at: string;
+    created_by: string | null;
+}
+interface CmsEntryListResponse {
+    entries: CmsEntry[];
+    total: number;
+    page: number;
+    page_size: number;
+}
+interface CmsIcon {
+    id: string;
+    name: string;
+    category: string;
+    tags: string[];
+}
+interface CmsIconListResponse {
+    icons: CmsIcon[];
+    total: number;
+}
+interface ListCmsEntriesParams {
+    page?: number;
+    page_size?: number;
+}
+interface CreateCmsEntryParams {
+    data: Record<string, any>;
+}
+interface UpdateCmsEntryParams {
+    data: Record<string, any>;
+}
+
+/**
+ * SdkContext
+ *
+ * Provides SdkConfig and the current access token to all SDK hooks
+ * in the component tree, so individual hooks do not require explicit
+ * config/accessToken parameters when called from client components.
+ *
+ * Usage in storefront:
+ *   // In your AuthProvider or root layout:
+ *   <SdkProvider config={sdkConfig} accessToken={accessToken}>
+ *     {children}
+ *   </SdkProvider>
+ *
+ *   // In any client component:
+ *   const { items, addItem } = useCart()  // no args needed
+ */
+
+interface SdkContextValue {
+    config: SdkConfig;
+    accessToken: string | null;
+}
+interface SdkProviderProps {
+    config: SdkConfig;
+    accessToken: string | null;
+    children: ReactNode;
+}
+declare function SdkProvider({ config, accessToken, children }: SdkProviderProps): React.JSX.Element;
+/**
+ * Returns the SdkContext value, or null if no SdkProvider is present.
+ * SDK hooks use this internally to fall back to context when explicit
+ * parameters are not provided.
+ */
+declare function useSdkContext(): SdkContextValue | null;
+/**
+ * Resolves config and accessToken from explicit arguments or SdkContext.
+ * Throws if neither source is available.
+ */
+declare function resolveHookArgs(explicitConfig: SdkConfig | undefined, explicitToken: string | null | undefined, ctx: SdkContextValue | null): {
+    config: SdkConfig;
+    accessToken: string | null;
+};
+
+export { type Inventory as $, type SupportedCurrenciesResponse as A, type CmsEntryListResponse as B, type CartResponse as C, type DVACreateRequest as D, type CheckoutCustomer as E, type FindOrderParams as F, type ShippingLocation as G, type DeliveryAddress as H, type Address as I, type AppContextValue as J, type AppState as K, type ListParams as L, type BackendLanguage as M, type BespokeStageKey as N, type Order as O, type Product as P, type CmsField as Q, type CmsIcon as R, type SdkConfig as S, type TransactionVerifyResponse as T, type UpdateCmsEntryParams as U, type CmsIconListResponse as V, type WishlistItem as W, type CmsModel as X, type CmsModelPermissions as Y, type CmsModelPublicApiPermissions as Z, type CustomField as _, type CartItem as a, type LangCode as a0, type OrderItem as a1, type OrderStatus as a2, type ProductType as a3, ServiceLocationTypeEnum as a4, type ServiceRecurringInterval as a5, ServiceRecurringIntervalEnum as a6, type ServiceType as a7, ServiceTypeEnum as a8, type ShippingRate as a9, type Theme as aa, type Country as b, type State as c, type SupportedLang as d, type Currency as e, type CmsEntry as f, type CreateCmsEntryParams as g, type ListCmsEntriesParams as h, type SdkContextValue as i, SdkProvider as j, type SdkProviderProps as k, type ServiceLocationType as l, type CreateOrderParams as m, type PaginatedResponse as n, type Collection as o, type WishlistCheckResponse as p, type WishlistListResponse as q, resolveHookArgs as r, type DVADetails as s, type PaymentInitiateRequest as t, useSdkContext as u, type PaymentInitiateResponse as v, type ConversionQuote as w, type ProductVariant as x, type ShippingRatesResponse as y, type SupportedLanguagesResponse as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kasuvia/sdk",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Kasuvia SDK - Core data fetching, authentication, and API client layer",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -10,6 +10,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "import": "./dist/hooks/index.mjs",
+      "require": "./dist/hooks/index.js"
     }
   },
   "files": [
@@ -22,7 +27,6 @@
   "dependencies": {
     "@microsoft/fetch-event-source": "^2.0.1",
     "@tanstack/react-query": "^5.100.13",
-    "axios": "^1.16.1",
     "graphql": "^16.14.0",
     "graphql-request": "^7.4.0",
     "react-use-websocket": "^4.13.0",

package/src/config/index.ts

@@ -1,102 +1,21 @@
 /**
  * Kasuvia SDK Configuration
  * 
- * This module manages SDK initialization and runtime configuration.
- * The SDK is client-based and runs in the browser.
- * All backend URLs are bundled with the SDK.
+ * Stateless configuration - no module-scoped state.
+ * All configuration is passed as parameters to SDK functions.
  * 
- * SECURITY NOTE: The storefront API key has limited permissions - it only provides
- * customer-based resources from a business owner to customers, not full platform access.
- * This key is safe to expose to the browser as a NEXT_PUBLIC_ environment variable.
+ * SECURITY NOTE: Backend URLs should never be exposed to the browser.
+ * They should only be used on the server side or in Next.js API routes.
  */
 
-import { logger, setEnvironmentMode, setLoggerEnvironmentMode } from "../utils"
-
 export interface SdkConfig {
   businessId: string
   storefrontApiKey: string
-}
-
-interface SdkRuntimeConfig {
-  businessId: string
-  storefrontApiKey: string
-}
-
-let runtimeConfig: SdkRuntimeConfig | null = null
-
-/**
- * Backend URLs - bundled with the SDK
- * These are the complete URLs (including API version) that the SDK uses internally.
- * The storefront never sees or configures these URLs.
- * 
- * Currently set to localhost development URLs.
- * Update to production URLs when ready for deployment.
- */
-const BACKEND_URLS = {
-  auth: 'https://127.0.0.1:8000/api/v1',
-  store: 'https://127.0.0.1:8001/api/v1',
-  payment: 'https://127.0.0.1:8002/api/v1',
-  notifications: 'https://127.0.0.1:8007/api/v1',
-  cms: 'https://127.0.0.1:8009/api/v1',
-} as const
-
-/**
- * Initialize the SDK with runtime credentials
- * This must be called before any SDK operations
- * 
- * IMPORTANT: In Next.js, this should be called in layout.tsx (server component)
- * using private environment variables (kasuvia_BUSINESS_ID, kasuvia_STOREFRONT_API_KEY).
- * The config is stored in module scope and will be available to client components
- * through the SDK's bundled code.
- * 
- * @param config - SDK configuration including credentials
- */
-export function initSdk(config: SdkConfig): void {
-  runtimeConfig = {
-    businessId: config.businessId,
-    storefrontApiKey: config.storefrontApiKey,
+  backendUrls: {
+    auth: string
+    store: string
+    payment: string
+    notifications: string
+    cms: string
   }
-  
-  // Determine environment from NODE_ENV for logging/cache behavior
-  // In browser (window exists), default to production behavior
-  // In Node.js (window undefined), check NODE_ENV
-  const isDevelopment = typeof window === 'undefined' && 
-    (globalThis as any).process?.env?.NODE_ENV === 'development'
-  setEnvironmentMode(isDevelopment)
-  setLoggerEnvironmentMode(isDevelopment)
-  
-  logger.log('SDK initialized with businessId:', config.businessId)
-}
-
-/**
- * Get the current runtime configuration
- * Throws if SDK is not initialized
- */
-export function getRuntimeConfig(): SdkRuntimeConfig {
-  if (!runtimeConfig) {
-    throw new Error('SDK not initialized. Call initSdk() before using SDK functions.')
-  }
-  return runtimeConfig
-}
-
-/**
- * Get backend URL for a specific service
- * Internal use only - never exposed to storefront
- */
-export function getBackendUrl(service: 'auth' | 'store' | 'payment' | 'notifications' | 'cms'): string {
-  return BACKEND_URLS[service]
-}
-
-/**
- * Check if SDK is initialized
- */
-export function isInitialized(): boolean {
-  return runtimeConfig !== null
-}
-
-/**
- * Reset SDK configuration (mainly for testing)
- */
-export function resetConfig(): void {
-  runtimeConfig = null
 }