TypeScript Types

The SDK exports all TypeScript types used across the Admin, Store, and Auth modules. Import them directly for type-safe application code.

Importing Types

import type {
  Product,
  Variant,
  Order,
  Cart,
  LineItem,
  Customer,
  Payment,
  Fulfillment,
  Region,
  Collection,
  Address,
} from '@hanzo/sdk'

Product Types

Product

interface Product {
  id: string
  name: string
  slug: string
  description: string | null
  status: 'draft' | 'published' | 'archived'
  price: number
  compareAtPrice: number | null
  currency: string
  images: ProductImage[]
  options: ProductOption[]
  variants: Variant[]
  collections: string[]
  tags: string[]
  metadata: Record<string, any>
  taxable: boolean
  createdAt: string
  updatedAt: string
}

interface ProductImage {
  id: string
  url: string
  alt: string | null
  position: number
}

interface ProductOption {
  id: string
  name: string
  values: string[]
}

Variant

interface Variant {
  id: string
  productId: string
  sku: string | null
  barcode: string | null
  title: string              // e.g. "Black / Medium"
  price: number
  compareAtPrice: number | null
  options: Record<string, string>  // e.g. { Color: "Black", Size: "M" }
  inventoryQuantity: number
  allowBackorders: boolean
  weight: number | null
  weightUnit: 'g' | 'kg' | 'lb' | 'oz' | null
  imageId: string | null
  metadata: Record<string, any>
  createdAt: string
  updatedAt: string
}

Order Types

Order

interface Order {
  id: string
  displayId: string             // Human-readable order number
  status: 'pending' | 'processing' | 'completed' | 'cancelled'
  paymentStatus: 'awaiting' | 'authorized' | 'captured' | 'refunded' | 'partially_refunded'
  fulfillmentStatus: 'unfulfilled' | 'partially_fulfilled' | 'fulfilled' | 'returned'
  customerId: string
  email: string
  items: LineItem[]
  shippingAddress: Address
  billingAddress: Address
  payments: Payment[]
  fulfillments: Fulfillment[]
  subtotal: number
  discountTotal: number
  taxTotal: number
  shippingTotal: number
  total: number
  currency: string
  regionId: string
  metadata: Record<string, any>
  createdAt: string
  updatedAt: string
}

LineItem

interface LineItem {
  id: string
  orderId: string | null
  cartId: string | null
  productId: string
  variantId: string
  title: string
  description: string | null
  thumbnail: string | null
  quantity: number
  unitPrice: number
  subtotal: number
  taxTotal: number
  total: number
  metadata: Record<string, any>
}

Cart Types

Cart

interface Cart {
  id: string
  regionId: string
  customerId: string | null
  email: string | null
  items: LineItem[]
  shippingAddress: Address | null
  billingAddress: Address | null
  shippingMethodId: string | null
  paymentMethodId: string | null
  discountCode: string | null
  subtotal: number
  discountTotal: number
  taxTotal: number
  shippingTotal: number
  total: number
  currency: string
  createdAt: string
  updatedAt: string
}

Customer Types

Customer

interface Customer {
  id: string
  email: string
  firstName: string | null
  lastName: string | null
  phone: string | null
  status: 'active' | 'disabled'
  groups: CustomerGroup[]
  addresses: Address[]
  metadata: Record<string, any>
  createdAt: string
  updatedAt: string
}

interface CustomerGroup {
  id: string
  name: string
  description: string | null
  createdAt: string
  updatedAt: string
}

Address

interface Address {
  id: string
  firstName: string
  lastName: string
  line1: string
  line2: string | null
  city: string
  state: string | null
  postalCode: string
  country: string           // ISO 3166-1 alpha-2
  phone: string | null
  isDefault: boolean
}

Payment Types

Payment

interface Payment {
  id: string
  orderId: string
  provider: string           // "stripe", "paypal", etc.
  status: 'pending' | 'authorized' | 'captured' | 'refunded' | 'failed'
  amount: number
  currency: string
  providerPaymentId: string  // External ID from payment provider
  capturedAt: string | null
  refundedAt: string | null
  metadata: Record<string, any>
  createdAt: string
  updatedAt: string
}

Fulfillment

interface Fulfillment {
  id: string
  orderId: string
  items: FulfillmentItem[]
  trackingNumber: string | null
  carrier: string | null
  status: 'pending' | 'shipped' | 'delivered' | 'cancelled'
  shippedAt: string | null
  deliveredAt: string | null
  metadata: Record<string, any>
  createdAt: string
  updatedAt: string
}

interface FulfillmentItem {
  itemId: string
  quantity: number
}

Region Types

Region

interface Region {
  id: string
  name: string
  currencyCode: string
  countries: string[]
  taxRate: number
  taxInclusive: boolean
  paymentProviders: string[]
  fulfillmentProviders: string[]
  metadata: Record<string, any>
  createdAt: string
  updatedAt: string
}

Collection Types

Collection

interface Collection {
  id: string
  name: string
  slug: string
  description: string | null
  type: 'manual' | 'automated'
  rules: CollectionRule[] | null
  imageUrl: string | null
  metadata: Record<string, any>
  createdAt: string
  updatedAt: string
}

interface CollectionRule {
  field: string
  operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains'
  value: string | number | boolean
}

Pagination Types

All list methods return a paginated response:

interface PaginatedResponse<T> {
  data: T[]
  count: number
  offset: number
  limit: number
}

Extending Types

Add custom fields using TypeScript intersection types:

import type { Product } from '@hanzo/sdk'

type CustomProduct = Product & {
  metadata: {
    brand: string
    warrantyMonths: number
  }
}

const product: CustomProduct = await sdk.admin.product.get('prod_abc123') as CustomProduct
console.log(product.metadata.brand)

Or extend with module augmentation:

declare module '@hanzo/sdk' {
  interface Product {
    customField?: string
  }
}

On this page