@behio/storefront-sdk 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -371,6 +371,51 @@ declare class BehioNetworkError extends Error {
     readonly isRetryable = true;
     constructor(message: string, isTimeout?: boolean);
 }
+/**
+ * Shape every SDK call returns. Destructure `{data, error}` — exactly
+ * one of them is non-null on any given call. No more try/catch for
+ * expected failures; the type system forces you to handle `error`
+ * before touching `data`.
+ *
+ *   const {data, error} = await behio.catalog.getProduct(slug);
+ *   if (error) return <ErrorState code={error.code} />;
+ *   return <ProductView product={data} />;
+ */
+type SdkResult<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: SdkError;
+};
+/**
+ * Canonical error shape returned from every SDK call. Always carries a
+ * `code` you can branch on without parsing messages.
+ */
+interface SdkError {
+    /**
+     * High-level category. `BehioErrorCode` covers API errors; additional
+     * buckets are network/timeout/abort/unknown.
+     */
+    code: BehioErrorCode;
+    /** Human-readable message (fallback for unknown codes / dev logging). */
+    message: string;
+    /** HTTP status, if the error came from the API. Null for network / abort. */
+    status: number | null;
+    /** Raw API body, if present. */
+    body?: unknown;
+    /** Whether the operation is safe to retry (true for 5xx / 429 / network). */
+    isRetryable: boolean;
+    /** Preserves the original thrown instance for stack traces + rethrows. */
+    cause?: unknown;
+}
+declare function ok<T>(data: T): SdkResult<T>;
+declare function err<T = never>(error: SdkError): SdkResult<T>;
+/**
+ * Converts any thrown value into a canonical SdkError. Used by the
+ * request wrapper when catching internal throws.
+ */
+declare function toSdkError(err: unknown): SdkError;
 type BehioEventType = "auth:login" | "auth:logout" | "auth:token-refresh" | "auth:token-refresh-failed" | "cart:updated" | "cart:cleared" | "order:created" | "error" | "request" | "response" | "rate-limit-warning";
 type BehioEventHandler = (data?: unknown) => void;
 interface RequestInterceptorConfig {
@@ -571,10 +616,11 @@ declare class BehioStorefront {
     readonly returns: ReturnsModule;
     readonly consent: ConsentModule;
     readonly quotes: QuotesModule;
+    readonly addresses: AddressModule;
     /** Get basic shop info */
-    getShopInfo(): Promise<ShopInfo>;
+    getShopInfo(): Promise<SdkResult<ShopInfo>>;
     /** Get SEO metadata for the shop homepage in the given locale (defaults to shop default). */
-    getShopSeo(locale?: string): Promise<ShopSeo>;
+    getShopSeo(locale?: string): Promise<SdkResult<ShopSeo>>;
     /** Set auth tokens (e.g. from localStorage) */
     setTokens(tokens: {
         accessToken: string;
@@ -606,88 +652,99 @@ declare class BehioStorefront {
         reset: number | null;
     };
     private handleTokenRefresh;
-    /** @internal */
+    /**
+     * Every public module method funnels through here. Internally calls
+     * `rawRequest` (which throws on failure) and maps thrown errors to
+     * `SdkError` so the public surface can return `SdkResult<T>`.
+     *
+     * @internal — don't call from outside the SDK; use the typed module
+     * methods (behio.catalog.*, behio.cart.*, …) instead.
+     */
     request<T>(method: string, path: string, options?: {
         body?: unknown;
         query?: Record<string, string | number | boolean | undefined | string[] | number[]>;
         auth?: boolean;
         signal?: AbortSignal;
-        /** @internal Prevents infinite refresh loops */
-        _isRetryAfterRefresh?: boolean;
-    }): Promise<T>;
+    }): Promise<SdkResult<T>>;
+    /**
+     * Throws on failure (API error / network / timeout). Kept private so
+     * internal auth refresh recursion keeps its existing control flow —
+     * public callers must go through `request()` which returns Result.
+     */
+    private rawRequest;
 }
 declare class CatalogModule {
     private client;
     constructor(client: BehioStorefront);
     /** List products with filtering, pagination, search */
-    getProducts(query?: ProductsQuery): Promise<PaginatedResponse<ProductListItem>>;
+    getProducts(query?: ProductsQuery): Promise<SdkResult<PaginatedResponse<ProductListItem>>>;
     /** Get product detail by slug */
     getProduct(slug: string, options?: {
         locale?: string;
         currency?: string;
-    }): Promise<ProductDetail>;
+    }): Promise<SdkResult<ProductDetail>>;
     /** Get category tree */
-    getCategories(locale?: string): Promise<{
+    getCategories(locale?: string): Promise<SdkResult<{
         categories: Category[];
-    }>;
+    }>>;
     /** Get category detail by slug */
-    getCategory(slug: string, locale?: string): Promise<CategoryDetail>;
+    getCategory(slug: string, locale?: string): Promise<SdkResult<CategoryDetail>>;
     /** Get products in a category */
-    getCategoryProducts(slug: string, query?: ProductsQuery): Promise<PaginatedResponse<ProductListItem>>;
+    getCategoryProducts(slug: string, query?: ProductsQuery): Promise<SdkResult<PaginatedResponse<ProductListItem>>>;
     /** Get all labels */
-    getLabels(locale?: string): Promise<{
+    getLabels(locale?: string): Promise<SdkResult<{
         labels: ProductLabel[];
-    }>;
+    }>>;
     /** Get featured products */
     getFeatured(options?: {
         locale?: string;
         currency?: string;
-    }): Promise<PaginatedResponse<ProductListItem>>;
+    }): Promise<SdkResult<PaginatedResponse<ProductListItem>>>;
     /** Get available filter fields for dynamic filter UI */
-    getFilters(): Promise<{
+    getFilters(): Promise<SdkResult<{
         filters: FilterField[];
-    }>;
+    }>>;
     /** Search products */
     search(query: string, options?: {
         page?: number;
         limit?: number;
-    }): Promise<PaginatedResponse<ProductListItem>>;
+    }): Promise<SdkResult<PaginatedResponse<ProductListItem>>>;
     /** List all active bundles */
-    getBundles(): Promise<{
+    getBundles(): Promise<SdkResult<{
         items: Bundle[];
-    }>;
+    }>>;
     /** Get a single bundle by slug */
-    getBundle(slug: string): Promise<Bundle>;
+    getBundle(slug: string): Promise<SdkResult<Bundle>>;
     /** Cross-sell / related / upsell products for a product */
-    getCrossSell(productSlug: string): Promise<{
+    getCrossSell(productSlug: string): Promise<SdkResult<{
         related: CrossSellItem[];
         upsell: CrossSellItem[];
         crossSell: CrossSellItem[];
-    }>;
+    }>>;
     /** Active promotions applicable to a product (with countdown end time) */
-    getProductPromotions(productSlug: string): Promise<{
+    getProductPromotions(productSlug: string): Promise<SdkResult<{
         items: ActivePromotion[];
-    }>;
+    }>>;
     /** Check a gift card code — returns validity and remaining balance */
-    checkGiftCard(code: string): Promise<GiftCardBalance>;
+    checkGiftCard(code: string): Promise<SdkResult<GiftCardBalance>>;
 }
 declare class AuthModule {
     private client;
     constructor(client: BehioStorefront);
     /** Register a new customer */
-    register(input: RegisterInput): Promise<AuthTokens>;
+    register(input: RegisterInput): Promise<SdkResult<AuthTokens>>;
     /** Login with email and password */
-    login(input: LoginInput): Promise<AuthTokens>;
+    login(input: LoginInput): Promise<SdkResult<AuthTokens>>;
     /** Refresh access token using refresh token */
-    refresh(refreshToken?: string): Promise<AuthTokens>;
+    refresh(refreshToken?: string): Promise<SdkResult<AuthTokens>>;
     /** Logout (invalidate refresh token) */
-    logout(refreshToken?: string): Promise<MessageResponse>;
+    logout(refreshToken?: string): Promise<SdkResult<MessageResponse>>;
     /** Request password reset email */
-    forgotPassword(email: string): Promise<MessageResponse>;
+    forgotPassword(email: string): Promise<SdkResult<MessageResponse>>;
     /** Reset password with token */
-    resetPassword(token: string, newPassword: string): Promise<MessageResponse>;
+    resetPassword(token: string, newPassword: string): Promise<SdkResult<MessageResponse>>;
     /** Verify email with token */
-    verifyEmail(token: string): Promise<MessageResponse>;
+    verifyEmail(token: string): Promise<SdkResult<MessageResponse>>;
     /** Check if user is logged in (has access token) */
     isLoggedIn(): boolean;
 }
@@ -695,39 +752,39 @@ declare class CartModule {
     private client;
     constructor(client: BehioStorefront);
     /** Get current cart */
-    get(): Promise<Cart>;
+    get(): Promise<SdkResult<Cart>>;
     /** Add item to cart */
-    addItem(input: AddToCartInput): Promise<Cart & {
+    addItem(input: AddToCartInput): Promise<SdkResult<Cart & {
         newSessionToken?: string;
-    }>;
+    }>>;
     /** Update item quantity */
-    updateQuantity(itemId: string, quantity: number): Promise<Cart>;
+    updateQuantity(itemId: string, quantity: number): Promise<SdkResult<Cart>>;
     /** Remove item from cart */
-    removeItem(itemId: string): Promise<Cart>;
+    removeItem(itemId: string): Promise<SdkResult<Cart>>;
     /** Clear entire cart */
-    clear(): Promise<void>;
+    clear(): Promise<SdkResult<void>>;
     /** Apply a gift card code to the cart. Balance is deducted at checkout. */
-    applyGiftCard(code: string): Promise<Cart>;
+    applyGiftCard(code: string): Promise<SdkResult<Cart>>;
     /** Remove a gift card from the cart */
-    removeGiftCard(): Promise<Cart>;
+    removeGiftCard(): Promise<SdkResult<Cart>>;
     /** Add a bundle to the cart (price is locked at the bundle's current price) */
-    addBundle(bundleId: string, quantity?: number): Promise<Cart>;
+    addBundle(bundleId: string, quantity?: number): Promise<SdkResult<Cart>>;
     /** Update quantity of a bundle already in the cart */
-    updateBundleQuantity(bundleId: string, quantity: number): Promise<Cart>;
+    updateBundleQuantity(bundleId: string, quantity: number): Promise<SdkResult<Cart>>;
     /** Remove a bundle from the cart */
-    removeBundle(bundleId: string): Promise<Cart>;
+    removeBundle(bundleId: string): Promise<SdkResult<Cart>>;
     /** Merge anonymous cart into authenticated customer cart */
-    merge(): Promise<Cart>;
+    merge(): Promise<SdkResult<Cart>>;
     /** Apply discount code */
-    applyDiscount(code: string): Promise<Cart>;
+    applyDiscount(code: string): Promise<SdkResult<Cart>>;
     /** Remove discount code */
-    removeDiscount(): Promise<Cart>;
+    removeDiscount(): Promise<SdkResult<Cart>>;
 }
 declare class CheckoutModule {
     private client;
     constructor(client: BehioStorefront);
     /** Create order from cart */
-    createOrder(input: CheckoutInput): Promise<OrderDetail>;
+    createOrder(input: CheckoutInput): Promise<SdkResult<OrderDetail>>;
 }
 declare class OrdersModule {
     private client;
@@ -736,92 +793,122 @@ declare class OrdersModule {
     list(options?: {
         page?: number;
         limit?: number;
-    }): Promise<PaginatedResponse<OrderListItem>>;
+    }): Promise<SdkResult<PaginatedResponse<OrderListItem>>>;
     /** Get order detail (requires auth) */
-    get(orderNumber: string): Promise<OrderDetail>;
+    get(orderNumber: string): Promise<SdkResult<OrderDetail>>;
     /** Cancel a PENDING order (requires auth) */
-    cancel(orderNumber: string): Promise<OrderDetail>;
+    cancel(orderNumber: string): Promise<SdkResult<OrderDetail>>;
     /** Track order by tracking token (no customer login required, only API key) */
-    track(trackingToken: string): Promise<OrderDetail>;
+    track(trackingToken: string): Promise<SdkResult<OrderDetail>>;
 }
 declare class CustomerModule {
     private client;
     constructor(client: BehioStorefront);
     /** Get customer profile */
-    getProfile(): Promise<CustomerProfile>;
+    getProfile(): Promise<SdkResult<CustomerProfile>>;
     /** Update customer profile */
-    updateProfile(data: Partial<Pick<CustomerProfile, "firstName" | "lastName" | "phone">>): Promise<CustomerProfile>;
+    updateProfile(data: Partial<Pick<CustomerProfile, "firstName" | "lastName" | "phone">>): Promise<SdkResult<CustomerProfile>>;
     /** Change password */
-    changePassword(currentPassword: string, newPassword: string): Promise<MessageResponse>;
+    changePassword(currentPassword: string, newPassword: string): Promise<SdkResult<MessageResponse>>;
     /** List addresses */
-    getAddresses(): Promise<{
+    getAddresses(): Promise<SdkResult<{
         items: CustomerAddress[];
-    }>;
+    }>>;
     /** Create address */
-    createAddress(address: Omit<CustomerAddress, "id">): Promise<CustomerAddress>;
+    createAddress(address: Omit<CustomerAddress, "id">): Promise<SdkResult<CustomerAddress>>;
     /** Update address */
-    updateAddress(addressId: string, data: Partial<CustomerAddress>): Promise<CustomerAddress>;
+    updateAddress(addressId: string, data: Partial<CustomerAddress>): Promise<SdkResult<CustomerAddress>>;
     /** Delete address */
-    deleteAddress(addressId: string): Promise<void>;
+    deleteAddress(addressId: string): Promise<SdkResult<void>>;
 }
 declare class PagesModule {
     private client;
     constructor(client: BehioStorefront);
     /** List CMS pages */
-    list(locale?: string): Promise<{
+    list(locale?: string): Promise<SdkResult<{
         pages: Page[];
-    }>;
+    }>>;
     /** Get page by slug */
-    get(slug: string, locale?: string): Promise<PageDetail>;
+    get(slug: string, locale?: string): Promise<SdkResult<PageDetail>>;
 }
 declare class WishlistModule {
     private client;
     constructor(client: BehioStorefront);
-    get(): Promise<{
+    get(): Promise<SdkResult<{
         items: WishlistItem[];
-    }>;
-    add(productId: string): Promise<{
+    }>>;
+    add(productId: string): Promise<SdkResult<{
         success: boolean;
-    }>;
-    remove(productId: string): Promise<{
+    }>>;
+    remove(productId: string): Promise<SdkResult<{
         success: boolean;
-    }>;
-    isInWishlist(productId: string): Promise<{
+    }>>;
+    isInWishlist(productId: string): Promise<SdkResult<{
         inWishlist: boolean;
-    }>;
+    }>>;
 }
 declare class ReviewsModule {
     private client;
     constructor(client: BehioStorefront);
-    getProductReviews(productId: string, page?: number, limit?: number): Promise<ProductReviewsResponse>;
-    submit(input: SubmitReviewInput): Promise<{
+    getProductReviews(productId: string, page?: number, limit?: number): Promise<SdkResult<ProductReviewsResponse>>;
+    submit(input: SubmitReviewInput): Promise<SdkResult<{
         id: string;
-    }>;
-    voteHelpful(reviewId: string, helpful: boolean): Promise<{
+    }>>;
+    voteHelpful(reviewId: string, helpful: boolean): Promise<SdkResult<{
         success: boolean;
-    }>;
+    }>>;
 }
 declare class ReturnsModule {
     private client;
     constructor(client: BehioStorefront);
-    submit(input: SubmitReturnInput): Promise<ReturnRequest>;
-    getStatus(returnId: string, email: string): Promise<ReturnRequest>;
+    submit(input: SubmitReturnInput): Promise<SdkResult<ReturnRequest>>;
+    getStatus(returnId: string, email: string): Promise<SdkResult<ReturnRequest>>;
 }
 declare class ConsentModule {
     private client;
     constructor(client: BehioStorefront);
-    record(input: CookieConsentInput): Promise<CookieConsent>;
-    get(visitorId: string): Promise<CookieConsent | null>;
-    revoke(visitorId: string): Promise<{
+    record(input: CookieConsentInput): Promise<SdkResult<CookieConsent>>;
+    get(visitorId: string): Promise<SdkResult<CookieConsent | null>>;
+    revoke(visitorId: string): Promise<SdkResult<{
         success: boolean;
-    }>;
+    }>>;
 }
 declare class QuotesModule {
     private client;
     constructor(client: BehioStorefront);
-    submit(input: SubmitQuoteInput): Promise<QuoteRequest>;
-    accept(quoteId: string, email: string): Promise<QuoteRequest>;
-    getStatus(quoteId: string): Promise<QuoteRequest>;
+    submit(input: SubmitQuoteInput): Promise<SdkResult<QuoteRequest>>;
+    accept(quoteId: string, email: string): Promise<SdkResult<QuoteRequest>>;
+    getStatus(quoteId: string): Promise<SdkResult<QuoteRequest>>;
+}
+interface AddressSuggestion {
+    placeId: string;
+    description: string;
+    street: string;
+    city: string;
+    zip: string;
+    country: string;
+    countryCode: string;
+}
+interface AddressDetail {
+    street: string;
+    streetNumber: string;
+    city: string;
+    zip: string;
+    country: string;
+    countryCode: string;
+    formattedAddress: string;
+    lat: number;
+    lng: number;
+}
+declare class AddressModule {
+    private client;
+    constructor(client: BehioStorefront);
+    /** Search for address suggestions (debounce on your side, or use the React hook) */
+    autocomplete(query: string, country: string): Promise<SdkResult<{
+        suggestions: AddressSuggestion[];
+    }>>;
+    /** Get full structured address from a suggestion's placeId */
+    getDetail(placeId: string): Promise<SdkResult<AddressDetail>>;
 }
 
-export { type ActivePromotion, type AddToCartInput, type AddressType, AddressTypes, type AuthTokens, BehioApiError, type BehioErrorCode, type BehioEventHandler, type BehioEventType, BehioNetworkError, BehioStorefront, type BehioStorefrontConfig, type Bundle, type BundleItem, type Cart, type CartDiscount, type CartItem, type CartItemProduct, type Category, type CategoryDetail, type CheckoutAddress, type CheckoutInput, type CookieConsent, type CookieConsentInput, type CrossSellItem, type CustomerAddress, type CustomerProfile, type DataGroupFieldType, type FilterField, type FulfillmentStatus, FulfillmentStatuses, type GiftCardBalance, type LoginInput, type MessageResponse, type OrderDetail, type OrderItem, type OrderListItem, type OrderStatus, type OrderStatusHistory, OrderStatuses, type Page, type PageDetail, type PaginatedResponse, type PaymentStatus, PaymentStatuses, type ProductDetail, type ProductLabel, type ProductListItem, type ProductPrice, type ProductReview, type ProductReviewsResponse, ProductSort, type ProductSortValue, type ProductVariant, type ProductVolumePrice, type ProductsQuery, type QuoteRequest, type RegisterInput, type RequestInterceptor, type RequestInterceptorConfig, type ResponseInterceptor, type ResponseInterceptorData, type ReturnRequest, type ShopInfo, type ShopSeo, type SubmitQuoteInput, type SubmitReturnInput, type SubmitReviewInput, type WishlistItem };
+export { type ActivePromotion, type AddToCartInput, type AddressDetail, type AddressSuggestion, type AddressType, AddressTypes, type AuthTokens, BehioApiError, type BehioErrorCode, type BehioEventHandler, type BehioEventType, BehioNetworkError, BehioStorefront, type BehioStorefrontConfig, type Bundle, type BundleItem, type Cart, type CartDiscount, type CartItem, type CartItemProduct, type Category, type CategoryDetail, type CheckoutAddress, type CheckoutInput, type CookieConsent, type CookieConsentInput, type CrossSellItem, type CustomerAddress, type CustomerProfile, type DataGroupFieldType, type FilterField, type FulfillmentStatus, FulfillmentStatuses, type GiftCardBalance, type LoginInput, type MessageResponse, type OrderDetail, type OrderItem, type OrderListItem, type OrderStatus, type OrderStatusHistory, OrderStatuses, type Page, type PageDetail, type PaginatedResponse, type PaymentStatus, PaymentStatuses, type ProductDetail, type ProductLabel, type ProductListItem, type ProductPrice, type ProductReview, type ProductReviewsResponse, ProductSort, type ProductSortValue, type ProductVariant, type ProductVolumePrice, type ProductsQuery, type QuoteRequest, type RegisterInput, type RequestInterceptor, type RequestInterceptorConfig, type ResponseInterceptor, type ResponseInterceptorData, type ReturnRequest, type SdkError, type SdkResult, type ShopInfo, type ShopSeo, type SubmitQuoteInput, type SubmitReturnInput, type SubmitReviewInput, type WishlistItem, err, ok, toSdkError };