Stylist SDK

A TypeScript SDK for interacting with the Stylist API. This SDK provides a simple and type-safe way to interact with the Stylist platform's API endpoints.

Features

• Type-safe API calls
• Authentication handling
• Cart management
• Error handling
• Response interceptors and middleware
• Swagger UI for testing and documentation
• shadcn UI components for consistent and accessible UI elements

Project Structure

StylistSDK/
├── src/                          # SDK source code
│   ├── config/                   # API configurations
│   ├── errors/                   # Error definitions
│   ├── interfaces/               # Type definitions
│   ├── middleware/               # Request/response interceptors
│   │   └── logging-middleware.ts # Debug logging
│   ├── services/                 # Core functionality
│   ├── ui/                       # UI components
│   │   └── shadcn/               # shadcn UI components
│   │       ├── components/       # Reusable UI components
│   │       ├── lib/              # Utility functions
│   │       └── styles/           # Global styles and themes
│   ├── utils/                    # Utility functions
│   │   └── network-controller.ts # HTTP request handling
│   └── index.ts                  # Main SDK entry point
├── swagger-ui/                   # Swagger UI testing interface
│   ├── src/                      # React components
│   │   └── components/           # Swagger UI component
│   └── public/                   # Static files
├── assets/                       # Build output
└── package.json                  # SDK dependencies

Installation

npm install @stylist/sdk

Usage

Initialization

import { StylistSDK } from '@stylist/sdk';

const sdk = new StylistSDK({
  baseUrl: 'https://stylist-master.xyretail.com',
  apiKey: 'your-api-key'
});

Authentication

// Verify user credentials
const authResponse = await sdk.auth.verifyCredentials({
  username: '[email protected]',
  password: 'password123'
});

// Handle authentication errors
try {
  await sdk.auth.verifyCredentials(credentials);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  }
}

Cart Management

// Create a new cart
const cart = await sdk.cart.createCart();

// Add items to cart
const cartItems = await sdk.cart.addItems(cart.cartId, {
  items: [{
    productId: '123',
    quantity: 1
  }]
});

// Get cart details
const cartDetails = await sdk.cart.getCart(cart.cartId);

// Remove item from cart
await sdk.cart.removeItemFromCart(cart.cartId, 'item-id');

// Set customer in cart
await sdk.cart.setCustomerInCart(cart.cartId, {
  id: 'customer-id',
  name: 'John Doe',
  email: '[email protected]'
});

// Navigate to cart
sdk.cart.goToCart({ 
  cartUri: '/cart/123',
  inApp: true // Set to false to open in new window
});

Response Interceptors

import { LoggingMiddleware } from '@stylist/sdk/middleware';

// Add logging middleware
sdk.addMiddleware(new LoggingMiddleware());

// Custom middleware example
class CustomMiddleware implements ResponseInterceptor {
  async onSuccess(response: Response): Promise<Response> {
    // Handle successful responses
    return response;
  }

  async onError(error: Error): Promise<never> {
    // Handle errors
    throw error;
  }
}

Error Handling

try {
  await sdk.cart.addItems(cartId, items);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Development

Prerequisites

• Node.js (v16 or higher)
• npm or yarn

Setup

1. Clone the repository
2. Install dependencies: npm install
3. Build the SDK: npm run build

UI Components

The SDK includes a set of reusable UI components built with shadcn/ui. These components are:

• Fully accessible
• Customizable through Tailwind CSS
• Dark mode compatible
• Type-safe with TypeScript

Available components:

• Button
• Input
• Card
• Badge

To use these components:

import { Button } from '@/ui/shadcn/components/button';
import { Input } from '@/ui/shadcn/components/input';
import { Card } from '@/ui/shadcn/components/card';
import { Badge } from '@/ui/shadcn/components/badge';

Testing Interface

The SDK includes a Swagger UI interface for testing API endpoints. To access it:

1. Navigate to the swagger-ui directory: cd swagger-ui
2. Install dependencies: npm install
3. Start the development server: npm run dev
4. Open http://localhost:5174 in your browser

The Swagger UI provides:

• Interactive API documentation
• Endpoint testing interface
• Request/response schemas
• Authentication testing

API Endpoints

Authentication

• /_a/actionSheet.xyidentity.VerifyCredentialsV2Action - Verify user credentials

Cart Management

• /cart - Create a new cart
• /cart/{cartId} - Get cart details
• /cart/{cartId}/items - Add items to cart

Error Handling

The SDK includes comprehensive error handling for various API scenarios:

try {
  await sdk.auth.verifyCredentials(credentials);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Handle authentication errors
  } else if (error instanceof ValidationError) {
    // Handle validation errors
  } else {
    // Handle other errors
  }
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add: amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.