@smart/contracts

Shared contracts, types, and schemas for Smart Platform

Installation

pnpm add @smart/contracts

Usage

HTTP Headers

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

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

Error Responses

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

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

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 |