@unidev-hub/api-contracts

A shared TypeScript interface package that serves as the contract between microfrontends and microservices in the UniDev Hub ecosystem.

Purpose

This package defines a standardized set of interfaces that act as the contract between frontend applications and backend services. By maintaining these interfaces in a single package, we ensure type consistency across our distributed architecture and improve developer experience.

Key Benefits

• Single Source of Truth: One definitive location for all interface definitions
• Type Safety: Catch integration issues at compile time rather than runtime
• Developer Experience: Autocompletion and IntelliSense support in IDEs
• Documentation: Interfaces serve as living documentation for your API
• Decoupling: Teams can develop independently while adhering to defined contracts

Installation

npm install @unidev-hub/api-contracts

Usage

In Frontend Applications

import { EcommerceContracts } from '@unidev-hub/api-contracts';

// Type a product object
const product: EcommerceContracts.Product = {
  id: '123e4567-e89b-12d3-a456-426614174000',
  name: 'Ergonomic Chair',
  // ... other properties according to the Product interface
};

// Type API responses
async function fetchProduct(id: string): Promise<EcommerceContracts.GetProductResponse> {
  const response = await fetch(`/api/products/${id}`);
  return response.json();
}

In Backend Services

import { ApiResponse, ErrorCode } from '@unidev-hub/api-contracts';
import { EcommerceContracts } from '@unidev-hub/api-contracts';

// Type your handlers
function getProductHandler(req, res): ApiResponse<EcommerceContracts.GetProductResponse> {
  const product = // retrieve product from database
  
  if (!product) {
    return {
      status: 404,
      data: null,
      error: {
        code: ErrorCode.NOT_FOUND,
        message: 'Product not found'
      },
      timestamp: Date.now()
    };
  }
  
  return {
    status: 200,
    data: { product },
    error: null,
    timestamp: Date.now()
  };
}

Package Structure

@unidev-hub/api-contracts/
├── src/
│   ├── core/               # Core interfaces
│   │   ├── request.types.ts  # Request-related interfaces
│   │   ├── response.types.ts # Response-related interfaces
│   │   └── error.types.ts    # Error handling interfaces
│   │
│   ├── domains/            # Domain-specific interfaces
│   │   ├── ecommerce/        # E-commerce domain
│   │   │   ├── product.types.ts
│   │   │   ├── order.types.ts
│   │   │   ├── customer.types.ts
│   │   │   ├── cart.types.ts
│   │   │   ├── payment.types.ts
│   │   │   ├── enums.ts
│   │   │   └── index.ts
│   │   │
│   │   └── ... other domains
│   │
│   └── index.ts            # Main export file

Domain: E-commerce

The E-commerce domain currently includes interfaces for:

• Products: Products, variants, images, attributes, and inventory
• Orders: Order processing, statuses, and fulfillment
• Customers: Customer data, addresses, and preferences
• Cart: Shopping cart management
• Payments: Payment methods and transactions

Extending the Package

To add new domains or expand existing ones:

1. Create appropriate TypeScript files in the relevant directory
2. Define your interfaces following package conventions
3. Export them from the domain's index.ts file
4. Update the main index.ts if needed
5. Build the package with npm run build

Versioning

This package follows semantic versioning:

• MAJOR version: Incompatible API changes
• MINOR version: Functionality added in a backward compatible manner
• PATCH version: Backward compatible bug fixes

Best Practices

• Don't import service implementations into this package - keep it pure interfaces
• Keep interface names consistent across domains
• Use descriptive names and JSDoc comments for clarity
• Include request and response interfaces for all API endpoints
• Group related interfaces in domain folders

License

ISC

Contact

For questions or suggestions, contact the UniDev Hub team.