wc-store-api-types

TypeScript types and Zod schemas for the WooCommerce Store API.

Installation

npm install wc-store-api-types

Usage

TypeScript Types

import type {
  ProductResponse,
  CartResponse,
  CheckoutRequest,
  CheckoutResponse,
} from 'wc-store-api-types'

// Use types for API responses
async function fetchProducts(): Promise<ProductResponse[]> {
  const response = await fetch('/wp-json/wc/store/v1/products')
  return response.json()
}

Zod Schema Validation

import {
  ProductResponseSchema,
  CartResponseSchema,
  CheckoutRequestSchema,
} from 'wc-store-api-types'

// Validate API responses at runtime
const response = await fetch('/wp-json/wc/store/v1/products/123')
const data = await response.json()

const product = ProductResponseSchema.parse(data) // Throws if invalid

// Safe parse (doesn't throw)
const result = ProductResponseSchema.safeParse(data)
if (result.success) {
  console.log(result.data.name)
} else {
  console.error(result.error.issues)
}

Validate Request Bodies

import { CheckoutRequestSchema } from 'wc-store-api-types'

const checkoutData = {
  billing_address: {
    first_name: 'John',
    last_name: 'Doe',
    email: '[email protected]',
    address_1: '123 Main St',
    city: 'New York',
    state: 'NY',
    postcode: '10001',
    country: 'US',
  },
  payment_method: 'cod',
}

// Validate before sending
const validatedData = CheckoutRequestSchema.parse(checkoutData)

Available Types

Product Types

• ProductResponse - Full product object
• ProductsResponse - Array of products
• ProductsRequest - Query parameters for product listings
• ProductCategoryResponse - Product category
• ProductBrandResponse - Product brand
• ProductAttributeResponse - Product attribute
• AttributeTermResponse - Attribute term
• ProductReviewResponse - Product review
• CollectionDataResponse - Aggregated collection data

Cart Types

• CartResponse - Full cart object
• CartItemResponse - Cart line item
• AddItemRequest - Add item to cart request
• UpdateItemRequest - Update cart item request
• RemoveItemRequest - Remove cart item request
• ApplyCouponRequest - Apply coupon request
• RemoveCouponRequest - Remove coupon request
• SelectShippingRateRequest - Select shipping rate request
• UpdateCustomerRequest - Update customer info request

Checkout Types

• CheckoutRequest - Place order request
• CheckoutResponse - Checkout/order response
• CheckoutUpdateRequest - Update draft order request
• PaymentResult - Payment result object

Address Types

• BillingAddress - Billing address
• ShippingAddress - Shipping address
• BaseAddress - Base address fields

Shipping Types

• ShippingPackage - Shipping package with rates
• ShippingRate - Individual shipping rate

Common Types

• CurrencyResponse - Currency information
• ImageResponse - Image attachment
• MonetaryValue - String representing monetary value
• StockStatus - Stock status enum

Auto-generating Types from API

This package includes scripts to generate types from live WooCommerce instances.

Fetch JSON Schemas

# Fetch from default sites (sites.json)
npm run generate:schemas

# Fetch from specific site
npm run generate:schemas -- --site https://example.com

Generate TypeScript from Schemas

npm run generate:types

Compare Generated vs Manual Types

npm run compare

Testing

Tests validate schemas against real WooCommerce API responses.

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

Configure test sites in sites.json:

{
  "sites": [
    "https://woocommerce.com",
    "https://your-wc-store.com"
  ]
}

Development

# Install dependencies
npm install

# Type check
npm run typecheck

# Build
npm run build

# Run tests
npm test

License

MIT