@eetech-commerce/cart-react 0.4.1

package/dist/index.d.ts

@@ -0,0 +1,663 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { QueryClient } from '@tanstack/react-query';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import react from 'react';
+
+interface StorageAdapter {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+
+declare const localStorageAdapter: StorageAdapter;
+
+interface CartContextValue {
+    tenantSlug: string;
+    cartApiUrl: string;
+    storage: StorageAdapter;
+    cartSessionId: string | null;
+    setCartSessionId: (id: string | null) => void;
+    isInitializing: boolean;
+    setIsInitializing: (value: boolean) => void;
+}
+declare function useCartContext(): CartContextValue;
+
+type TaxJurisdictionDto = {
+    /**
+     * ISO 3166-1 alpha-2 country code
+     */
+    country: string;
+    /**
+     * State/province code (if applicable)
+     */
+    state?: string;
+    /**
+     * Type of tax (e.g., sales_tax, vat, gst)
+     */
+    taxType: string;
+};
+type LineItemResponseDto = {
+    /**
+     * Unique identifier for the line item
+     */
+    id: string;
+    /**
+     * Product identifier
+     */
+    productId: string;
+    /**
+     * Product variant identifier
+     */
+    variantId?: string | null;
+    /**
+     * Offer identifier
+     */
+    offerId: string;
+    /**
+     * Seller identifier
+     */
+    sellerId: string;
+    /**
+     * Seller display name
+     */
+    sellerName?: string | null;
+    /**
+     * Product manufacturer name
+     */
+    manufacturer: string;
+    /**
+     * Product title
+     */
+    title: string;
+    /**
+     * Product variant title
+     */
+    variantTitle?: string | null;
+    /**
+     * Product thumbnail URL
+     */
+    thumbnail?: string | null;
+    /**
+     * Quantity of items
+     */
+    quantity: number;
+    /**
+     * Unit price in cents
+     */
+    unitPriceCents: number;
+    /**
+     * Subtotal in cents (quantity × unit price)
+     */
+    subtotalCents: number;
+    /**
+     * Product availability status
+     */
+    availability?: 'available' | 'unavailable' | 'not_found';
+    /**
+     * Additional metadata
+     */
+    metadata?: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * Product weight in pounds (from MarketPush product data)
+     */
+    weightPounds?: string | null;
+    /**
+     * Calculated tax amount in cents (populated after shipping address is set)
+     */
+    taxAmountCents?: number;
+    /**
+     * Tax rate as percentage (populated after shipping address is set)
+     */
+    taxRatePercentage?: number;
+    /**
+     * Tax jurisdiction details (populated after shipping address is set)
+     */
+    taxJurisdiction?: TaxJurisdictionDto | null;
+    /**
+     * Stripe Tax Calculation ID for audit trail
+     */
+    taxCalculationId?: string;
+    /**
+     * Timestamp when tax was calculated
+     */
+    taxCalculatedAt?: Date;
+    /**
+     * Reason for tax rate applied or exemption
+     */
+    taxabilityReason?: 'standard_rated' | 'reduced_rated' | 'zero_rated' | 'exempt' | 'reverse_charge' | 'not_collecting';
+    /**
+     * Creation timestamp
+     */
+    createdAt: Date;
+    /**
+     * Last update timestamp
+     */
+    updatedAt: Date;
+};
+type CustomerContactDto = {
+    /**
+     * Customer email address
+     */
+    email: string;
+    /**
+     * Customer first name
+     */
+    firstName: string;
+    /**
+     * Customer last name
+     */
+    lastName: string;
+    /**
+     * Primary phone number (minimum 10 characters)
+     */
+    phone: string;
+    /**
+     * Alternative phone number (minimum 10 characters)
+     */
+    alterPhone?: string;
+};
+type Address = {
+    /**
+     * Address ID
+     */
+    id: string;
+    /**
+     * Tenant ID
+     */
+    tenantId: string;
+    /**
+     * Recipient name
+     */
+    recipientName?: string | null;
+    /**
+     * Company name
+     */
+    company?: string | null;
+    /**
+     * Address line 1
+     */
+    line1: string;
+    /**
+     * Address line 2
+     */
+    line2?: string | null;
+    /**
+     * City
+     */
+    city: string;
+    /**
+     * State
+     */
+    state: string;
+    /**
+     * Zipcode
+     */
+    zipcode: string;
+    /**
+     * Country
+     */
+    country: string;
+    /**
+     * Creation timestamp
+     */
+    createdAt: Date;
+    /**
+     * Full formatted address
+     */
+    fullAddress: string;
+};
+type CartResponseDto = {
+    /**
+     * Internal database ID
+     */
+    id: string;
+    /**
+     * Public cart session identifier (nanoid)
+     */
+    sessionId: string;
+    /**
+     * Three-letter currency code (ISO 4217)
+     */
+    currency: string;
+    /**
+     * Cart subtotal in cents
+     */
+    subtotalCents: number;
+    /**
+     * Completion timestamp (null if cart is active)
+     */
+    completedAt?: Date | null;
+    /**
+     * Line items in the cart
+     */
+    items: Array<LineItemResponseDto>;
+    /**
+     * Optional cart metadata
+     */
+    metadata?: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * Cart creation timestamp
+     */
+    createdAt: Date;
+    /**
+     * Last update timestamp
+     */
+    updatedAt: Date;
+    /**
+     * Web order ID (nanoid) - present when checkout session created
+     */
+    webOrderId?: string | null;
+    /**
+     * Customer contact information - present when checkout session created
+     */
+    customerContact?: CustomerContactDto | null;
+    /**
+     * Shipping address - present when checkout session created
+     */
+    shippingAddress?: Address | null;
+    /**
+     * Billing address - present when checkout session created
+     */
+    billingAddress?: Address | null;
+    /**
+     * Shipping selections by seller ID - present when shipping methods selected
+     */
+    shippingSelections?: {
+        [key: string]: {
+            [key: string]: unknown;
+        };
+    } | null;
+    /**
+     * Purchase order number
+     */
+    poNumber?: string | null;
+};
+type DiscrepancyDto = {
+    /**
+     * Type of discrepancy detected
+     */
+    type: 'price_change' | 'unavailable' | 'insufficient_stock' | 'offer_removed' | 'seller_inactive' | 'below_minimum_order';
+    /**
+     * Cart line item ID
+     */
+    itemId: string;
+    /**
+     * Product offer ID
+     */
+    offerId: string;
+    /**
+     * Human-readable description of the discrepancy
+     */
+    message: string;
+    /**
+     * Original price in cents (for price_change)
+     */
+    oldPrice?: number;
+    /**
+     * New price in cents (for price_change)
+     */
+    newPrice?: number;
+    /**
+     * Quantity requested (for insufficient_stock)
+     */
+    requested?: number;
+    /**
+     * Quantity available (for insufficient_stock)
+     */
+    available?: number;
+    /**
+     * Reason for unavailability
+     */
+    reason?: 'out_of_stock' | 'inactive';
+    /**
+     * Seller ID (for seller-level discrepancies)
+     */
+    sellerId?: string;
+    /**
+     * Seller name (for seller-level discrepancies)
+     */
+    sellerName?: string;
+    /**
+     * Minimum order value in dollars (for below_minimum_order)
+     */
+    minimumOrderValue?: number;
+    /**
+     * Current order subtotal in dollars (for below_minimum_order)
+     */
+    currentSubtotal?: number;
+};
+type VerificationResultDto = {
+    /**
+     * Whether all cart items passed verification
+     */
+    valid: boolean;
+    /**
+     * Cart session ID that was verified
+     */
+    cartId: string;
+    /**
+     * List of discrepancies found during verification
+     */
+    discrepancies: Array<DiscrepancyDto>;
+    /**
+     * Total number of items verified
+     */
+    itemCount: number;
+    /**
+     * ISO timestamp of verification
+     */
+    verifiedAt: string;
+};
+type AddressDto = {
+    /**
+     * Name of the recipient
+     */
+    recipientName?: string;
+    /**
+     * Company name
+     */
+    company?: string;
+    /**
+     * First line of the address
+     */
+    line1: string;
+    /**
+     * Second line of the address (apartment, suite, etc.)
+     */
+    line2?: string;
+    /**
+     * City name
+     */
+    city: string;
+    /**
+     * State or province
+     */
+    state: string;
+    /**
+     * Postal/ZIP code
+     */
+    zipcode: string;
+    /**
+     * Three-letter country code (ISO 3166-1 alpha-3)
+     */
+    country: string;
+};
+type CreateCheckoutDto = {
+    /**
+     * Customer contact information
+     */
+    customerContact: CustomerContactDto;
+    /**
+     * Shipping address
+     */
+    shippingAddress: AddressDto;
+    /**
+     * Billing address (can be same as shipping)
+     */
+    billingAddress: AddressDto;
+    /**
+     * Purchase order number (optional)
+     */
+    poNumber?: string;
+};
+type ShippingOptionDto = {
+    /**
+     * Shipping option UUID (used as shippingRateId in selections)
+     */
+    id: string;
+    /**
+     * Seller this option belongs to
+     */
+    sellerId: string;
+    /**
+     * Delivery method name
+     */
+    deliveryMethod: string;
+    /**
+     * Carrier name
+     */
+    carrierName: string;
+    /**
+     * Carrier key for API integration
+     */
+    carrierKey: string;
+    /**
+     * Shipping option type (pricing model)
+     */
+    shippingOptionType: 'FreeShipping' | 'FlatRate' | 'PriceBasedRate' | 'WeightBasedRate';
+    /**
+     * Shipping cost in dollars
+     */
+    cost: number;
+    /**
+     * Creation timestamp (ISO 8601)
+     */
+    createdDate: string;
+    /**
+     * Last update timestamp (ISO 8601)
+     */
+    updatedDate: string;
+};
+type SellerShippingOptions = {
+    /**
+     * Seller UUID
+     */
+    sellerId: string;
+    /**
+     * Seller display name
+     */
+    sellerName: string | null;
+    /**
+     * Available shipping options for this seller
+     */
+    shippingOptions: Array<ShippingOptionDto>;
+};
+type ShippingOptionsResponse = {
+    /**
+     * Cart session ID
+     */
+    cartSessionId: string;
+    /**
+     * Shipping options grouped by seller
+     */
+    sellers: Array<SellerShippingOptions>;
+};
+type ShippingSelectionDto = {
+    /**
+     * Seller UUID this selection applies to
+     */
+    sellerId: string;
+    /**
+     * MarketPush shipping rate ID used for this selection
+     */
+    shippingRateId: string;
+    /**
+     * Optional carrier account identifier (max 50 chars, alphanumeric + dash/underscore/slash)
+     */
+    carrierAccount?: string;
+};
+type ShippingSelectionsResponseDto = {
+    /**
+     * Cart session ID
+     */
+    cartSessionId: string;
+    /**
+     * Shipping selections by seller ID
+     */
+    shippingSelections: {
+        [key: string]: {
+            [key: string]: unknown;
+        };
+    };
+};
+type PaymentSessionResponseDto = {
+    /**
+     * Unique payment session identifier
+     */
+    paymentSessionId: string;
+    /**
+     * Stripe Checkout Session URL
+     */
+    paymentLink: string;
+    /**
+     * Payment amount in cents
+     */
+    amount: number;
+    /**
+     * Three-letter currency code
+     */
+    currency: string;
+    /**
+     * Payment session status
+     */
+    status: 'pending' | 'succeeded' | 'failed' | 'expired';
+    /**
+     * Session expiration timestamp
+     */
+    expiresAt: Date;
+};
+type CreateEmbeddedPaymentSessionDto = {
+    /**
+     * Cart session ID (nanoid format) to create payment for
+     */
+    cartSessionId: string;
+    /**
+     * URL where Stripe redirects after payment completion
+     */
+    returnUrl: string;
+};
+type EmbeddedPaymentSessionResponseDto = {
+    /**
+     * Unique payment session identifier
+     */
+    paymentSessionId: string;
+    /**
+     * Stripe client secret for initEmbeddedCheckout()
+     */
+    clientSecret: string;
+    /**
+     * Payment amount in cents
+     */
+    amount: number;
+    /**
+     * Three-letter currency code (lowercase)
+     */
+    currency: string;
+};
+
+interface MutationCallbacks<TData = unknown, TError = Error> {
+    onSuccess?: (data: TData) => void;
+    onError?: (error: TError) => void;
+}
+
+declare function useCart(): _tanstack_react_query.UseQueryResult<CartResponseDto, Error>;
+interface CreateCartParams {
+    currency?: string;
+    metadata?: Record<string, unknown>;
+}
+declare function useCreateCart(): {
+    createCart: (params?: CreateCartParams, callbacks?: MutationCallbacks<CartResponseDto>) => void;
+    isPending: boolean;
+    error: Error | null;
+};
+interface AddToCartParams {
+    offerId: string;
+    quantity?: number;
+    metadata?: Record<string, unknown>;
+}
+declare function useAddToCart(): {
+    addToCart: (params: AddToCartParams, callbacks?: MutationCallbacks<CartResponseDto>) => void;
+    isPending: boolean;
+    error: Error | null;
+};
+interface UpdateItemQtyParams {
+    offerId: string;
+    quantity: number;
+}
+declare function useUpdateItemQty(): {
+    updateItemQty: (params: UpdateItemQtyParams, callbacks?: MutationCallbacks<CartResponseDto>) => void;
+    isPending: boolean;
+    error: Error | null;
+};
+interface RemoveItemParams {
+    offerId: string;
+}
+declare function useRemoveItem(): {
+    removeItem: (params: RemoveItemParams, callbacks?: MutationCallbacks<CartResponseDto>) => void;
+    isPending: boolean;
+    error: Error | null;
+};
+declare function useClearCart(): {
+    clearCart: (callbacks?: MutationCallbacks<CartResponseDto>) => void;
+    isPending: boolean;
+    error: Error | null;
+};
+declare function useInitializeCart(): {
+    isInitializing: boolean;
+};
+
+declare function useVerifyCart(): {
+    verifyCart: (params: {
+        cartSessionId: string;
+    }, callbacks?: MutationCallbacks<VerificationResultDto>) => void;
+    isPending: boolean;
+    error: Error | null;
+};
+declare function useCreateCheckoutSession(): {
+    createCheckoutSession: (params: CreateCheckoutDto & {
+        cartSessionId?: string;
+    }, callbacks?: MutationCallbacks<CartResponseDto>) => void;
+    isPending: boolean;
+    error: Error | null;
+};
+declare function useShippingOptions(cartSessionId: string | null): _tanstack_react_query.UseQueryResult<ShippingOptionsResponse, Error>;
+interface UpdateShippingSelectionsParams {
+    selections: ShippingSelectionDto[];
+}
+declare function useUpdateShippingSelections(): {
+    updateShippingSelections: (params: UpdateShippingSelectionsParams, callbacks?: MutationCallbacks<ShippingSelectionsResponseDto>) => void;
+    isPending: boolean;
+    error: Error | null;
+};
+
+declare function useStripePromise(): Promise<unknown> | null;
+declare function useCreateEmbeddedCheckoutSession(): {
+    createEmbeddedCheckoutSession: (params: CreateEmbeddedPaymentSessionDto, callbacks?: MutationCallbacks<EmbeddedPaymentSessionResponseDto>) => void;
+    isPending: boolean;
+    error: Error | null;
+    data: EmbeddedPaymentSessionResponseDto | undefined;
+};
+declare function usePaymentSession(sessionId: string | null): _tanstack_react_query.UseQueryResult<PaymentSessionResponseDto, Error>;
+
+declare const cartKeys: {
+    all: () => readonly [{
+        readonly _id: "cartControllerGetCartV1";
+    }];
+};
+declare const shippingKeys: {
+    all: () => readonly [{
+        readonly _id: "checkoutControllerGetShippingOptionsV1";
+    }];
+};
+declare const paymentKeys: {
+    all: () => readonly [{
+        readonly _id: "paymentControllerGetPaymentSessionV1";
+    }];
+};
+
+interface CartProviderProps {
+    children: react.ReactNode;
+    tenantSlug: string;
+    cartApiUrl: string;
+    storageAdapter?: StorageAdapter;
+    autoInitialize?: boolean;
+    /** Optional external QueryClient. If provided, CartProvider will not create its own. */
+    queryClient?: QueryClient;
+}
+declare function CartProvider({ children, tenantSlug, cartApiUrl, storageAdapter, autoInitialize, queryClient, }: CartProviderProps): react_jsx_runtime.JSX.Element;
+
+export { type CartContextValue, CartProvider, type CartProviderProps, type CartResponseDto, type CreateCheckoutDto, type CreateEmbeddedPaymentSessionDto, type EmbeddedPaymentSessionResponseDto, type LineItemResponseDto, type MutationCallbacks, type ShippingOptionDto, type ShippingSelectionDto, type StorageAdapter, type VerificationResultDto, cartKeys, localStorageAdapter, paymentKeys, shippingKeys, useAddToCart, useCart, useCartContext, useClearCart, useCreateCart, useCreateCheckoutSession, useCreateEmbeddedCheckoutSession, useInitializeCart, usePaymentSession, useRemoveItem, useShippingOptions, useStripePromise, useUpdateItemQty, useUpdateShippingSelections, useVerifyCart };