npm package: @mehdashti/contracts
Description: Shared contracts, types, and schemas for Smart Platform
Author: mehdashti
Latest version: 0.1.1

# @smart/contracts

> Shared contracts, types, and schemas for Smart Platform

## Installation

```bash
pnpm add @smart/contracts
```

## Usage

### HTTP Headers

```typescript
import { HTTP_HEADERS, type PlatformHeaders } from "@smart/contracts/http";

// Use standard header names
const correlationId = headers[HTTP_HEADERS.CORRELATION_ID];
```

### Error Responses

```typescript
import {
  createValidationError,
  createNotFoundError,
  type ErrorResponse,
} from "@smart/contracts/errors";

// Create validation error
const error = createValidationError("/api/users", correlationId, [
  { field: "email", message: "Invalid email format" },
]);

// Create not found error
const notFound = createNotFoundError("User", "/api/users/123", correlationId);
```

### Pagination

```typescript
import {
  createPaginatedResponse,
  parseSort,
  normalizePaginationParams,
  type PaginatedResponse,
} from "@smart/contracts/pagination";

// Parse sort parameter
const sort = parseSort("-created_at"); // { field: "created_at", direction: "desc" }

// Create paginated response
const response = createPaginatedResponse(users, 1, 20, 100);
```

### Health Checks

```typescript
import {
  createReadinessResponse,
  measureHealthCheck,
} from "@smart/contracts/health";

// Measure database health
const dbCheck = await measureHealthCheck("database", async () => {
  await db.query("SELECT 1");
});

// Create response
const response = createReadinessResponse([dbCheck], "1.0.0");
```

## API Reference

### HTTP Module (`@smart/contracts/http`)

| Export                   | Description                       |
| ------------------------ | --------------------------------- |
| `HTTP_HEADERS`           | Standard header name constants    |
| `DEFAULT_RETRY_CONFIG`   | Default retry configuration       |
| `SAFE_METHODS`           | HTTP methods safe for retry       |
| `UNSAFE_METHODS`         | HTTP methods requiring idempotency|

### Errors Module (`@smart/contracts/errors`)

| Export                   | Description                       |
| ------------------------ | --------------------------------- |
| `createErrorResponse`    | Create standard error response    |
| `createValidationError`  | Create validation error           |
| `createNotFoundError`    | Create not found error            |
| `isErrorResponse`        | Type guard for error responses    |
| `ERROR_STATUS_MAP`       | Error type to status code mapping |

### Pagination Module (`@smart/contracts/pagination`)

| Export                     | Description                     |
| -------------------------- | ------------------------------- |
| `createPaginatedResponse`  | Create paginated response       |
| `parseSort`                | Parse sort string               |
| `serializeSort`            | Serialize sort to string        |
| `normalizePaginationParams`| Validate/normalize pagination   |
| `DEFAULT_PAGINATION`       | Default pagination params       |

### Health Module (`@smart/contracts/health`)

| Export                   | Description                       |
| ------------------------ | --------------------------------- |
| `createLivenessResponse` | Create /health response           |
| `createReadinessResponse`| Create /ready response            |
| `measureHealthCheck`     | Measure check with timing         |
| `HEALTH_ENDPOINTS`       | Standard endpoint paths           |