Behio Storefront SDK
Advanced

TypeScript Types

Complete type reference for the SDK

TypeScript Types

Complete reference of all types exported by @behio/storefront-sdk. All types are fully exported and can be imported directly:

import type { ProductDetail, Cart, CheckoutInput } from "@behio/storefront-sdk";

Configuration

BehioStorefrontConfig

interface BehioStorefrontConfig {
  /** API key (public: pk_live_xxx or private: sk_live_xxx) */
  apiKey: string;
  /** Backend base URL. Default: https://api.behio.com */
  baseUrl?: string;
  /** Default locale for catalog requests. Default: none (uses shop default) */
  locale?: string;
  /** Default currency for price resolution. Default: none (uses shop default) */
  currency?: string;
  /** Custom fetch implementation (for Node.js < 18 or testing) */
  fetch?: typeof fetch;
  /** Request timeout in milliseconds. Default: 30000 (30s) */
  timeout?: number;
  /** Number of retries on network/5xx errors. Default: 1 */
  retries?: number;
  /** Base delay between retries in ms (multiplied by attempt). Default: 1000 */
  retryDelay?: number;
}

Products

ProductListItem

Represents a product in list/collection views.

interface ProductListItem {
  id: string;
  slug: string;
  name: string;
  shortDescription?: string;
  sku: string;
  gtin?: string;
  price: ProductPrice;
  inStock: boolean;
  stockQuantity?: number;
  image?: string | null;
  labels: ProductLabel[];
  isFeatured: boolean;
}

ProductDetail

Full product detail, extends ProductListItem.

interface ProductDetail extends ProductListItem {
  longDescription?: string;
  images: Array<{ url: string; alt?: string; order: number }>;
  categories: Array<{ id: string; slug: string; name: string }>;
  variants: ProductVariant[];
  volumePricing: ProductVolumePrice[];
  customFields: Record<string, unknown>;
  seo: {
    title?: string | null;
    description?: string | null;
    keywords?: string | null;
  };
  productGroups?: Array<{
    slug: string;
    name: string;
    products: ProductListItem[];
  }>;
  /** Product weight (from warehouse item) */
  weight?: number | null;
  /** Weight unit: GRAM, KILOGRAM, TONNE */
  weightUnit?: string | null;
}

ProductPrice

interface ProductPrice {
  amount: number;
  currency: string;
  compareAtPrice?: number | null;
}

ProductVolumePrice

interface ProductVolumePrice {
  minQuantity: number;
  price: number;
  currency?: string;
}

ProductVariant

interface ProductVariant {
  id: string;
  sku: string;
  name: string;
  attributes: Record<string, string>;
  price: ProductPrice;
  inStock: boolean;
  stockQuantity?: number;
}

ProductLabel

interface ProductLabel {
  id: string;
  slug: string;
  name: string;
  color?: string;
}

ProductsQuery

Query parameters for listing products.

interface ProductsQuery {
  page?: number;
  limit?: number;
  /** Single category slug (OR logic with categories array) */
  category?: string;
  /** Multiple category slugs (OR logic) */
  categories?: string[];
  /** Single label slug */
  label?: string;
  priceMin?: number;
  priceMax?: number;
  currency?: string;
  locale?: string;
  sort?: ProductSortValue;
  inStock?: boolean;
  search?: string;
  customFields?: Record<string, unknown>;
  /** Filter by specific product IDs */
  ids?: string[];
  /** Filter by specific product slugs */
  slugs?: string[];
  /** Multiple labels (AND logic — product must have ALL) */
  labels?: string[];
  /** Exclude specific product IDs */
  excludeIds?: string[];
  /** Exclude products in specific categories */
  excludeCategories?: string[];
  /** Only products with compareAtPrice (on sale) */
  hasDiscount?: boolean;
  /** Only featured products */
  isFeatured?: boolean;
  /** Products created after timestamp (epoch ms) */
  createdAfter?: number;
}

ProductSort

Available sort values (const object for runtime + autocomplete):

const ProductSort = {
  PRICE_ASC: "price_asc",
  PRICE_DESC: "price_desc",
  NAME_ASC: "name_asc",
  NAME_DESC: "name_desc",
  NEWEST: "newest",
  FEATURED: "featured",
} as const;

type ProductSortValue = (typeof ProductSort)[keyof typeof ProductSort];

FilterField

interface FilterField {
  key: string;
  name: string;
  type: DataGroupFieldType | string;
  groupKey: string;
  groupName: string;
  values?: string[];
}

DataGroupFieldType

type DataGroupFieldType =
  | "TEXT" | "NUMBER" | "DECIMAL" | "BOOLEAN"
  | "DATE" | "TIME" | "DATETIME"
  | "PERCENTAGE" | "MONEY" | "ASSET"
  | "ITEM_LIST" | "DYNAMIC_NUMBER_CALCULATION_FROM_OTHERS";

Categories

Category

interface Category {
  id: string;
  slug: string;
  name: string;
  description?: string;
  imageUrl?: string;
  children: Category[];
  productCount?: number;
}

CategoryDetail

Extends Category with SEO fields.

interface CategoryDetail extends Category {
  seoTitle?: string;
  seoDescription?: string;
}

Cart

Cart

interface Cart {
  id: string;
  sessionToken?: string;
  items: CartItem[];
  subtotal: number;
  discountTotal: number;
  discount?: CartDiscount;
  grandTotal: number;
  currency: string;
  itemCount: number;
}

CartItem

interface CartItem {
  id: string;
  product: CartItemProduct;
  quantity: number;
  unitPrice: number;
  totalPrice: number;
  priceChanged: boolean;
  volumePriceApplied: boolean;
}

CartItemProduct

interface CartItemProduct {
  slug: string;
  name: string;
  sku: string;
  imageUrl?: string;
  inStock: boolean;
  currentPrice: number;
}

CartDiscount

interface CartDiscount {
  code: string;
  type: string;
  value: number;
}

AddToCartInput

interface AddToCartInput {
  /** Product ID (eshop product ID or warehouse item ID) */
  productId: string;
  quantity: number;
}

Checkout

CheckoutInput

interface CheckoutInput {
  shippingAddress: CheckoutAddress;
  billingAddress: CheckoutAddress;
  email: string;
  phone?: string;
  customerNote?: string;
}

CheckoutAddress

interface CheckoutAddress {
  firstName: string;
  lastName: string;
  company?: string;
  street: string;
  city: string;
  zip: string;
  country: string;
  phone?: string;
}

OrderDetail

Full order detail returned after checkout, extends OrderListItem.

interface OrderDetail extends OrderListItem {
  items: OrderItem[];
  shippingAddress: CheckoutAddress;
  billingAddress: CheckoutAddress;
  email: string;
  phone?: string;
  customerNote?: string;
  subtotal: number;
  taxTotal: number;
  shippingTotal: number;
  discountTotal: number;
  fulfillmentStatus: FulfillmentStatus;
  statusHistory: OrderStatusHistory[];
  trackingToken?: string;
}

Orders

OrderListItem

interface OrderListItem {
  id: string;
  orderNumber: string;
  status: OrderStatus;
  paymentStatus: PaymentStatus;
  grandTotal: number;
  currency: string;
  itemCount: number;
  createdAt: number;
}

OrderItem

interface OrderItem {
  productName: string;
  sku: string;
  imageUrl?: string;
  quantity: number;
  unitPrice: number;
  totalPrice: number;
  totalPriceWithTax: number;
}

OrderStatusHistory

interface OrderStatusHistory {
  fromStatus?: OrderStatus;
  toStatus: OrderStatus;
  note?: string;
  changedBy?: string;
  createdAt: number;
}

Status enums

const OrderStatuses = {
  PENDING: "PENDING",
  CONFIRMED: "CONFIRMED",
  PROCESSING: "PROCESSING",
  SHIPPED: "SHIPPED",
  DELIVERED: "DELIVERED",
  CANCELLED: "CANCELLED",
  REFUNDED: "REFUNDED",
} as const;
type OrderStatus = (typeof OrderStatuses)[keyof typeof OrderStatuses];

const PaymentStatuses = {
  UNPAID: "UNPAID",
  PAID: "PAID",
  PARTIALLY_REFUNDED: "PARTIALLY_REFUNDED",
  REFUNDED: "REFUNDED",
} as const;
type PaymentStatus = (typeof PaymentStatuses)[keyof typeof PaymentStatuses];

const FulfillmentStatuses = {
  UNFULFILLED: "UNFULFILLED",
  PARTIALLY_FULFILLED: "PARTIALLY_FULFILLED",
  FULFILLED: "FULFILLED",
} as const;
type FulfillmentStatus = (typeof FulfillmentStatuses)[keyof typeof FulfillmentStatuses];

Auth

AuthTokens

interface AuthTokens {
  accessToken: string;
  refreshToken: string;
}

RegisterInput

interface RegisterInput {
  email: string;
  password: string;
  firstName?: string;
  lastName?: string;
}

LoginInput

interface LoginInput {
  email: string;
  password: string;
}

Customer

CustomerProfile

interface CustomerProfile {
  id: string;
  email: string;
  firstName?: string;
  lastName?: string;
  phone?: string;
  emailVerified: boolean;
}

CustomerAddress

interface CustomerAddress {
  id: string;
  type: AddressType;
  isDefault: boolean;
  firstName: string;
  lastName: string;
  company?: string;
  street: string;
  city: string;
  zip: string;
  country: string;
  phone?: string;
}

AddressType

const AddressTypes = {
  SHIPPING: "SHIPPING",
  BILLING: "BILLING",
} as const;
type AddressType = (typeof AddressTypes)[keyof typeof AddressTypes];

Bundles

Bundle

interface Bundle {
  id: string;
  slug: string;
  name: string;
  description: string | null;
  bundlePrice: number;
  currency: string;
  coverImage: string | null;
  endsAt: number | null;
  itemsSum: number;
  savings: number;
  savingsPercent: number;
  items: BundleItem[];
}

BundleItem

interface BundleItem {
  productId: string;
  slug: string | null;
  name: string;
  sku: string;
  quantity: number;
  imageUrl: string | null;
  defaultPrice: number | null;
}

Cross-sell

CrossSellItem

interface CrossSellItem {
  productId: string;
  slug: string | null;
  name: string;
  sku: string;
  price: number | null;
  imageUrl: string | null;
  stockCached: number;
}

Promotions

ActivePromotion

interface ActivePromotion {
  id: string;
  name: string;
  slug: string;
  type: string;
  discountType: string;
  discountValue: number;
  startsAt: number;
  endsAt: number | null;
  badgeText: string | null;
  badgeColor: string | null;
  showCountdown: boolean;
  couponRequired: boolean;
}

Gift Cards

GiftCardBalance

interface GiftCardBalance {
  valid: boolean;
  balance: number;
  currency: string;
}

Wishlist

WishlistItem

interface WishlistItem {
  id: string;
  productId: string;
  productName: string;
  productSku: string;
  productSlug: string | null;
  imageUrl: string | null;
  price: number | null;
  stockCached: number;
  createdAt: number;
}

Reviews

ProductReviewsResponse

interface ProductReviewsResponse {
  items: ProductReview[];
  averageRating: number;
  reviewCount: number;
  page: number;
  totalPages: number;
}

ProductReview

interface ProductReview {
  id: string;
  authorName: string;
  rating: number;
  title: string | null;
  content: string | null;
  imageUrls: string[];
  isVerifiedPurchase: boolean;
  helpfulCount: number;
  unhelpfulCount: number;
  replyContent: string | null;
  createdAt: number;
}

SubmitReviewInput

interface SubmitReviewInput {
  productId: string;
  rating: number;
  title?: string;
  content?: string;
  authorName: string;
  authorEmail?: string;
  imageUrls?: string[];
}

Returns

ReturnRequest

interface ReturnRequest {
  id: string;
  orderId: string;
  status: string;
  reason: string;
  customerNote: string | null;
  refundAmount: number | null;
  refundMethod: string | null;
  createdAt: number;
}

SubmitReturnInput

interface SubmitReturnInput {
  orderId: string;
  reason: string;
  customerNote?: string;
  items: {
    orderItemId: string;
    productName: string;
    quantity: number;
    reason?: string;
    imageUrls?: string[];
  }[];
}

CookieConsent

interface CookieConsent {
  necessary: boolean;
  analytics: boolean;
  marketing: boolean;
  preferences: boolean;
  consentedAt: number;
}

CookieConsentInput

interface CookieConsentInput {
  visitorId: string;
  analytics: boolean;
  marketing: boolean;
  preferences: boolean;
}

Quotes (B2B)

QuoteRequest

interface QuoteRequest {
  id: string;
  status: string;
  contactName: string;
  contactEmail: string;
  companyName: string | null;
  quotedTotal: number | null;
  createdAt: number;
}

SubmitQuoteInput

interface SubmitQuoteInput {
  contactName: string;
  contactEmail: string;
  contactPhone?: string;
  companyName?: string;
  companyIco?: string;
  message?: string;
  items: {
    productId: string;
    quantity: number;
    requestedPrice?: number;
  }[];
}

Pages

Page

interface Page {
  slug: string;
  title: string;
  isActive: boolean;
}

PageDetail

interface PageDetail {
  slug: string;
  title: string;
  content: unknown;
  seoTitle?: string;
  seoDescription?: string;
}

Shop

ShopInfo

interface ShopInfo {
  id: string;
  name: string;
  domain: string;
  logo?: string;
  favicon?: string;
  isActive: boolean;
  defaultLanguage: string;
  supportedLanguages: string[];
  defaultCurrency: string;
  supportedCurrencies: string[];
  metaTitle?: string;
  metaDescription?: string;
  allowGuestCheckout: boolean;
}

ShopSeo

interface ShopSeo {
  locale: string;
  title: string | null;
  description: string | null;
  keywords: string | null;
  ogTitle: string | null;
  ogDescription: string | null;
  ogImage: string | null;
}

Errors

BehioApiError

Thrown for HTTP error responses from the API.

class BehioApiError extends Error {
  readonly code: BehioErrorCode;
  readonly status: number;
  readonly body: unknown;
  readonly isRetryable: boolean;

  constructor(status: number, body: unknown, message?: string);

  /** Check if this is a specific error type */
  is(code: BehioErrorCode): boolean;
}

BehioNetworkError

Thrown for network failures and timeouts.

class BehioNetworkError extends Error {
  readonly code: "NETWORK_ERROR" | "TIMEOUT";
  readonly isRetryable: true;

  constructor(message: string, isTimeout?: boolean);
}

BehioErrorCode

type BehioErrorCode =
  | "UNAUTHORIZED"
  | "FORBIDDEN"
  | "NOT_FOUND"
  | "VALIDATION_ERROR"
  | "CONFLICT"
  | "RATE_LIMITED"
  | "CART_EMPTY"
  | "PRODUCT_NOT_FOUND"
  | "INVALID_CREDENTIALS"
  | "INVALID_DISCOUNT"
  | "DISCOUNT_EXPIRED"
  | "TOKEN_EXPIRED"
  | "TOKEN_INVALID"
  | "EMAIL_ALREADY_EXISTS"
  | "ORDER_NOT_CANCELLABLE"
  | "INTERNAL_ERROR"
  | "NETWORK_ERROR"
  | "TIMEOUT"
  | "UNKNOWN";

Events

BehioEventType

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";

BehioEventHandler

type BehioEventHandler = (data?: unknown) => void;

Interceptors

RequestInterceptor

interface RequestInterceptorConfig {
  url: string;
  method: string;
  headers: Record<string, string>;
  body?: string;
}

type RequestInterceptor = (
  config: RequestInterceptorConfig,
) => RequestInterceptorConfig | Promise<RequestInterceptorConfig>;

ResponseInterceptor

interface ResponseInterceptorData {
  status: number;
  data: unknown;
  headers: Headers;
}

type ResponseInterceptor = (
  response: ResponseInterceptorData,
) => void | Promise<void>;

Pagination

PaginatedResponse

Generic wrapper for paginated list endpoints.

interface PaginatedResponse<T> {
  items: T[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

MessageResponse

interface MessageResponse {
  message: string;
}

On this page