@kasuvia/sdk 0.0.7 → 0.0.9

package/dist/index-CNW_LINy.d.mts

@@ -0,0 +1,578 @@
+/**
+ * Shipping and delivery types for the storefront
+ */
+interface ShippingRate {
+    id: string;
+    carrier_name: string;
+    carrier_logo: string | null;
+    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;
+    /**
+     * 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;
+}
+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;
+    latitude?: number | null;
+    longitude?: number | null;
+    plus_code?: string | null;
+    coordinate_source?: CoordinateSource;
+}
+interface AddressValidationErrorData {
+    message: string;
+    errorType?: 'state' | 'city' | 'general';
+    cities?: Array<{
+        name: string;
+        city_id: string;
+        stateCode: string;
+        countryCode: string;
+    }>;
+    states?: Array<{
+        name: string;
+        code: string;
+        countryCode: string;
+    }>;
+}
+type CoordinateSource = 'pin_drop' | 'plus_code' | 'manual' | null;
+interface GeolocationData {
+    latitude?: number | null;
+    longitude?: number | null;
+    plus_code?: string | null;
+    coordinate_source?: CoordinateSource;
+}
+interface ReverseGeocodeRequest {
+    latitude: number;
+    longitude: number;
+}
+interface ReverseGeocodeResponse {
+    city: string | null;
+    state: string | null;
+    country: string | null;
+    country_code: string | null;
+    display_name: string | null;
+}
+interface PlusCodeDecodeRequest {
+    plus_code: string;
+}
+interface PlusCodeDecodeResponse {
+    latitude: number;
+    longitude: number;
+    latitude_lo: number;
+    longitude_hi: number;
+    plus_code: string;
+}
+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;
+}
+interface AddressAutocompleteResponse {
+    results: AddressSuggestion[];
+}
+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;
+}
+
+declare enum ProductTypeEnum {
+    PHYSICAL = "physical",
+    DIGITAL = "digital",
+    SERVICE = "service",
+    BESPOKE = "bespoke"
+}
+type ProductType = ProductTypeEnum | "physical" | "digital" | "service" | "bespoke";
+declare enum ServiceTypeEnum {
+    APPOINTMENT = "appointment",
+    PROJECT = "project",
+    RECURRING = "recurring"
+}
+type ServiceType = ServiceTypeEnum | 'appointment' | 'project' | 'recurring';
+declare enum ServiceLocationTypeEnum {
+    REMOTE = "remote",
+    AT_BUSINESS = "at_business",
+    CUSTOMER_LOCATION = "customer_location"
+}
+type ServiceLocationType = ServiceLocationTypeEnum | 'remote' | 'at_business' | 'customer_location';
+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;
+    collection_type?: string;
+    /** 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;
+    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;
+    length_cm?: number;
+    width_cm?: number;
+    height_cm?: number;
+    is_active: boolean;
+    inventory?: Inventory;
+}
+interface CustomField {
+    label: string;
+    unit?: string;
+    required: boolean;
+    /** "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. */
+interface ProductDigitalFile {
+    id: string;
+    file_key: string;
+    display_name: string;
+    sort_order: number;
+}
+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;
+    is_non_returnable?: boolean;
+    deposit_percentage?: number;
+    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;
+    /** 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_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;
+    service_buffer_minutes?: number;
+    service_is_recurring?: boolean;
+    service_recurring_interval?: ServiceRecurringInterval;
+    service_project_based?: boolean;
+    weight_kg?: number;
+    length_cm?: number;
+    width_cm?: number;
+    height_cm?: number;
+    variants?: ProductVariant[];
+    collections?: Collection[];
+    inventory?: Inventory;
+    created_at: string;
+    updated_at: string;
+}
+interface ProductListResponse {
+    items: Product[];
+    total: number;
+    page: number;
+    page_size: number;
+    total_pages: number;
+}
+interface CollectionListResponse {
+    items: Collection[];
+    total: number;
+    page: number;
+    page_size: number;
+    total_pages: number;
+}
+interface ListParams {
+    page?: number;
+    pageSize?: number;
+    collectionSlug?: string;
+    search?: string;
+    excludeProductId?: string;
+    /** One of physical/digital/service/bespoke — omit to browse the whole catalog. */
+    productType?: ProductType;
+}
+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_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;
+}
+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?: ProductType;
+}
+interface WishlistItem {
+    id: string;
+    product_id: string;
+    notes?: string;
+    created_at: string;
+    product_name?: string;
+    product_slug?: string;
+    product_price?: number;
+    /**
+     * 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;
+}
+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' | 'ready_for_pickup' | 'picked_up_by_customer' | 'in_transit' | 'shipped' | 'delivered' | 'voided' | 'refunded' | 'failed';
+interface OrderItem {
+    id: string;
+    order_id?: string;
+    product_id?: string;
+    variant_id?: string;
+    product_name: string;
+    quantity: number;
+    unit_price: number;
+    variant_details?: Record<string, unknown>;
+    custom_measurements?: Record<string, unknown>;
+    image_url?: string;
+}
+interface Order {
+    id: string;
+    display_id: string;
+    business_id: string;
+    customer_id?: string;
+    status: OrderStatus;
+    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;
+    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;
+    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_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;
+    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?: string;
+    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;
+    latitude?: number | null;
+    longitude?: number | null;
+    plus_code?: string | null;
+    coordinate_source?: 'pin_drop' | 'plus_code' | 'manual' | null;
+}
+interface FindOrderParams {
+    email: string;
+    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).
+ */
+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. */
+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.
+ */
+interface CreateOrderParams {
+    customer_id?: string | null;
+    status?: string;
+    checkout_session_id?: string;
+    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;
+        unit_price: number;
+        variant_id?: string;
+        variant_details?: Record<string, unknown>;
+        custom_measurements?: Record<string, unknown>;
+    }>;
+    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;
+    guest_token?: string;
+    guest_email?: string;
+    guest_phone?: string;
+    guest_name?: string;
+    product_type?: ProductType;
+    bespoke_brief?: string;
+    bespoke_reference_images?: string[];
+    bespoke_measurements?: Record<string, string>;
+    bespoke_preferred_timeline?: string;
+    bespoke_special_instructions?: string;
+}
+
+export { type Address as A, ServiceLocationTypeEnum as B, type CreateOrderParams as C, type DeliveryAddress as D, type ServiceRecurringInterval as E, type FindOrderParams as F, type GeolocationData as G, ServiceRecurringIntervalEnum as H, type Inventory as I, type ServiceType as J, ServiceTypeEnum as K, type ListParams as L, type ShippingAddressPayload as M, type ShippingRate as N, type Order as O, type Product as P, type ShippingRatesResponse as Q, type ReverseGeocodeRequest as R, type ShippingLocation as S, type WishlistItem as W, type CartItem as a, type CartResponse as b, type Collection as c, type PaginatedResponse as d, type WishlistCheckResponse as e, type WishlistListResponse as f, type CheckoutCustomer as g, type ProductType as h, type OrderStatus as i, type AddressAutocompleteResponse as j, type AddressSuggestion as k, type AddressValidationErrorData as l, type CollectionListResponse as m, type CoordinateSource as n, type CreateOrderDigitalParams as o, type CreateOrderPhysicalParams as p, type CustomField as q, type OrderItem as r, type PlusCodeDecodeRequest as s, type PlusCodeDecodeResponse as t, type ProductDigitalFile as u, type ProductListResponse as v, ProductTypeEnum as w, type ProductVariant as x, type ReverseGeocodeResponse as y, type ServiceLocationType as z };