@lecxa/shipstation-zod

Zod schemas for ShipStation API v2 - Runtime validation and type-safe schema definitions.

Features

• ✅ Runtime Validation - Validate API responses at runtime
• 🔒 Type-Safe - Infer TypeScript types from schemas
• 🚀 Zodios Integration - Pre-configured Zodios client
• 📦 Tree-Shakeable - Import only the schemas you need
• 🔄 Auto-Generated - Always up-to-date with latest API changes

Installation

npm install @lecxa/shipstation-zod zod
# or
pnpm add @lecxa/shipstation-zod zod
# or
yarn add @lecxa/shipstation-zod zod

Peer Dependencies

• zod ^3.0.0

Quick Start

Basic Schema Validation

import { schemas } from '@lecxa/shipstation-zod';
import { z } from 'zod';

// Validate a shipment object
const shipmentData = {
  shipment_id: 'se_123456',
  carrier_id: 'se_789',
  // ... other fields
};

const validatedShipment = schemas.shipment.parse(shipmentData);

// Type-safe! TypeScript knows the structure
console.log(validatedShipment.shipment_id); // string

Zodios Client (Recommended)

Use the pre-configured Zodios client for automatic validation:

import { api } from '@lecxa/shipstation-zod';

// The API client automatically validates responses
const shipments = await api.get('/shipments', {
  params: { page: 1, page_size: 50 },
  headers: {
    Authorization: 'Bearer your-api-token',
  },
});

// TypeScript + Runtime validation!
// shipments is fully typed AND validated at runtime

Create Custom Zodios Client

import { createApiClient } from '@lecxa/shipstation-zod';

const client = createApiClient('https://api.shipstation.com/', {
  validate: true, // Enable runtime validation (default: true)
  headers: {
    Authorization: 'Bearer your-api-token',
  },
});

// Use the client
const label = await client.post('/labels', {
  shipment: {
    ship_to: { /* ... */ },
    ship_from: { /* ... */ },
    packages: [{ weight: { value: 1.5, unit: 'pound' } }],
  },
  carrier_code: 'stamps_com',
  service_code: 'usps_priority_mail',
});

Available Schemas

All ShipStation API schemas are available:

import { schemas } from '@lecxa/shipstation-zod';

// Core entities
schemas.shipment
schemas.label
schemas.carrier
schemas.rate
schemas.warehouse
schemas.batch
schemas.manifest

// Request/Response types
schemas.createLabelBody
schemas.createLabelResponse
schemas.listShipmentsParams
schemas.listShipmentsResponseBody

// And many more...

Type Inference

Infer TypeScript types from schemas:

import { schemas } from '@lecxa/shipstation-zod';
import { z } from 'zod';

// Infer the type
type Shipment = z.infer<typeof schemas.shipment>;
type CreateLabelBody = z.infer<typeof schemas.createLabelBody>;

// Use in your code
const processShipment = (shipment: Shipment) => {
  console.log(shipment.shipment_id); // Type-safe!
};

Validation with Error Handling

import { schemas } from '@lecxa/shipstation-zod';

try {
  const validatedData = schemas.createLabelBody.parse(userInput);
  // Data is valid, proceed
} catch (error) {
  if (error instanceof z.ZodError) {
    console.error('Validation errors:', error.errors);
    // Handle specific validation errors
    error.errors.forEach((err) => {
      console.log(`${err.path.join('.')}: ${err.message}`);
    });
  }
}

Safe Parsing

Use safeParse for non-throwing validation:

import { schemas } from '@lecxa/shipstation-zod';

const result = schemas.shipment.safeParse(data);

if (result.success) {
  // data is valid
  console.log(result.data);
} else {
  // data is invalid
  console.error(result.error.errors);
}

Partial Validation

Validate partial objects:

import { schemas } from '@lecxa/shipstation-zod';

// Allow partial updates
const partialShipment = schemas.shipment.partial().parse({
  shipment_id: 'se_123456',
  // Other fields are optional
});

Custom Validation

Extend schemas with custom validation:

import { schemas } from '@lecxa/shipstation-zod';
import { z } from 'zod';

const customShipmentSchema = schemas.shipment.extend({
  custom_field: z.string().min(5),
}).refine(
  (data) => data.weight.value > 0,
  { message: 'Weight must be positive' }
);

Integration with Forms

Great for form validation:

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { schemas } from '@lecxa/shipstation-zod';

const CreateLabelForm = () => {
  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(schemas.createLabelBody),
  });

  const onSubmit = (data) => {
    // data is validated and type-safe!
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      {/* form fields */}
    </form>
  );
};

Zodios Features

The Zodios client provides additional features:

• Automatic request/response validation
• Type-safe API calls
• Error handling with typed errors
• Plugin system for interceptors
• Automatic retry logic

import { createApiClient } from '@lecxa/shipstation-zod';

const client = createApiClient('https://api.shipstation.com/', {
  validate: 'all', // Validate requests and responses
  transform: 'response', // Transform responses
});

// All responses are automatically validated
const validated = await client.get('/shipments/:id', {
  params: { id: 'se_123456' },
});

TypeScript Support

All schemas are fully typed:

import type { schemas } from '@lecxa/shipstation-zod';

License

MIT © Lecxa