@kasuvia/sdk 0.0.2 → 0.0.4

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

@@ -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 };