TypeScript Types

Complete type definitions for the SDK

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.

Config

Configuration Types

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

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

Response

API Response Types

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

Store

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

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

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

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

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.