TypeScript Types

The SDK is written in TypeScript and exports all type definitions. Install via npm to get full IntelliSense support.

All async SDK methods return SDKResponse<T> — a wrapper containing data, error, and status fields. See the Response tab below for the full definition.

Configuration Types

interface ShoppexConfig {
  storeSlug: string;
  locale?: string;
  currency?: string;
  apiBaseUrl?: string;
}

interface ShoppexInitOptions {
  locale?: string;
  currency?: string;
  apiBaseUrl?: string;
}

API Response Types

interface SDKResponse<T> {
  success: boolean;
  data?: T;
  message?: string;
}

Store Types

interface Shop {
  id: string;
  name: string;
  slug: string;
  domain?: string;
  description?: string;
  currency: string;
  logo?: string;
  banner?: string;
  rating?: number;
  tos_enabled?: boolean;
}

Product Types

interface ProductCategory {
  uniqid: string;
  title: string;
}

interface Product {
  uniqid: string;
  title: string;
  slug?: string;
  description?: string;
  price: string;           // String for precision
  price_display?: string;  // Formatted display price
  currency: string;
  stock?: number;
  cdn_image_url?: string | null;    // Card/listing/search image
  detail_image_url?: string | null; // PDP/gallery/zoom image
  images: ProductImage[];
  variants?: ProductVariant[];
  addons?: ProductAddon[];
  price_variants?: PriceVariant[];
  custom_fields?: string | unknown[] | null;
  categories?: ProductCategory[];
}

interface ProductImage {
  id: string;
  url: string;
  cloudflare_image_id?: string;
  alt?: string;
}

interface ProductVariant {
  id: string;
  title: string;
  price?: number;
  stock?: number;
}

interface ProductAddon {
  id: string;
  name: string;
  price: number;
  required?: boolean;
}

interface PriceVariant {
  id: string;
  label: string;
  price: number;
}

interface CustomFieldDefinition {
  id: string;
  name: string;
  type: 'text' | 'textarea' | 'select' | 'checkbox';
  required?: boolean;
  options?: string[];
}

Image fields have different jobs:

cdn_image_url is the optimized storefront cover for cards and lists
detail_image_url is the higher-resolution primary image for product detail pages
images[] contains the gallery

If you run a headless storefront, you should normally keep cards on cdn_image_url and switch your PDP hero/gallery to detail_image_url.

Cart Types

interface CartItem {
  product_id: string;
  variant_id: string;
  quantity: number;
  addons?: CartAddon[];
  custom_fields?: Record<string, string>;
  price_variant_id?: string;
}

interface CartAddon {
  id: string;
  quantity?: number;
}

interface CartAddOptions {
  addons?: CartAddon[];
  custom_fields?: Record<string, string>;
  price_variant_id?: string;
}

interface CartUpdateOptions {
  quantity?: number;
  addons?: CartAddon[];
  custom_fields?: Record<string, string>;
  price_variant_id?: string;
}

Checkout Types

interface CheckoutOptions {
  autoRedirect?: boolean;
  locale?: string;
}

interface CheckoutResult {
  success: boolean;
  redirectUrl?: string;
  message?: string;
}

interface CouponValidation {
  valid: boolean;
  discount?: number;
  discount_type?: 'percentage' | 'fixed';
  message?: string;
}

Invoice Types

interface Invoice {
  uniqid: string;
  status: string;
  total: number;
  currency: string;
  gateway?: string;
  products: InvoiceProduct[];
  created_at: string;
}

interface InvoiceProduct {
  product_id: string;
  title: string;
  quantity: number;
  price: number;
}

Review Types

interface Feedback {
  id: string;
  rating: number;
  comment?: string;
  created_at: string;
}

Error Types

class ShoppexError extends Error {
  readonly code: string;
  readonly statusCode?: number;
}

class NotInitializedError extends ShoppexError {
  // Thrown when SDK methods are called before init()
  // code: 'NOT_INITIALIZED'
}

class NetworkError extends ShoppexError {
  // Thrown on HTTP/network failures
  // code: 'NETWORK_ERROR'
}

class ValidationError extends ShoppexError {
  // Thrown on input validation failures
  // code: 'VALIDATION_ERROR'
  readonly invalidFields?: string[];
}

class CartError extends ShoppexError {
  // Thrown on cart operation errors
  // code: 'BASKET_ERROR'
}

Usage with TypeScript

import shoppex, {
  type Product,
  type ProductVariant,
  type CartItem,
  type Invoice,
  type SDKResponse
} from '@shoppexio/storefront';

// Initialize
shoppex.init('my-store');

// Typed responses
async function loadProducts(): Promise<Product[]> {
  const response: SDKResponse<Product[]> = await shoppex.getProducts();

  if (!response.success || !response.data) {
    throw new Error(response.message || 'Failed to load products');
  }

  return response.data;
}

// Type-safe cart operations
function addProductToCart(product: Product, variant?: ProductVariant): void {
  shoppex.addToCart(
    product.uniqid,
    variant?.id ?? '',
    1
  );
}

// Typed invoice handling
async function checkOrderStatus(invoiceId: string): Promise<string> {
  const { data } = await shoppex.getInvoiceStatus(invoiceId);
  return data.status;
}

See the individual API reference pages for detailed usage examples of each type: Products, Cart, Checkout, and Store.

Getting Started

API Reference

Resources

TypeScript Types

Configuration Types

API Response Types

Store Types

Product Types

Cart Types

Checkout Types

Invoice Types

Review Types

Error Types

Usage with TypeScript

​Configuration Types

​API Response Types

​Store Types

​Product Types

​Cart Types

​Checkout Types

​Invoice Types

​Review Types

​Error Types

​Usage with TypeScript

Configuration Types

API Response Types

Store Types

Product Types

Cart Types

Checkout Types

Invoice Types

Review Types

Error Types

Usage with TypeScript