FarmPro API Contracts

Type-safe API contracts for FarmPro API using ts-rest and Zod.

Overview

This package provides comprehensive, type-safe API contracts for all FarmPro modules. The contracts follow RESTful principles and use Zod schemas for runtime validation.

Installation

npm install @farmpro/contracts

Structure

The contracts are organized into modules:

src/
├── index.ts                 # Main exports
├── routes/                  # API route definitions
│   ├── index.ts            # Main contract combining all routers
│   ├── farms.routes.ts
│   ├── fields.routes.ts
│   ├── tasks.routes.ts
│   ├── inventory.routes.ts
│   ├── finance.routes.ts
│   ├── harvest.routes.ts
│   ├── soil-tests.routes.ts
│   ├── weather.routes.ts
│   ├── team.routes.ts
│   ├── equipment.routes.ts
│   ├── documents.routes.ts
│   ├── suppliers.routes.ts
│   └── analytics.routes.ts
└── schemas/                 # Zod schemas
    ├── common.schemas.ts   # Shared schemas (pagination, errors, GeoJSON)
    ├── farms.schemas.ts
    ├── fields.schemas.ts
    ├── tasks.schemas.ts
    ├── inventory.schemas.ts
    ├── finance.schemas.ts
    ├── harvest.schemas.ts
    ├── soil-tests.schemas.ts
    ├── weather.schemas.ts
    ├── team.schemas.ts
    ├── equipment.schemas.ts
    ├── documents.schemas.ts
    ├── suppliers.schemas.ts
    └── analytics.schemas.ts

Usage

Backend (NestJS)

import { apiContract } from '@farmpro/contracts';
import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';

@Controller()
export class FarmsController {
  @TsRestHandler(apiContract.farms)
  async handler() {
    return tsRestHandler(apiContract.farms, {
      listFarms: async ({ query }) => {
        // Implementation
      },
      createFarm: async ({ body }) => {
        // Implementation
      },
      // ... other handlers
    });
  }
}

Frontend

import { initClient } from '@ts-rest/core';
import { apiContract } from '@farmpro/contracts';

const client = initClient(apiContract, {
  baseUrl: 'http://localhost:3000/api',
  baseHeaders: {
    'Content-Type': 'application/json',
  },
});

// Use the client
const farms = await client.farms.listFarms({ query: { page: 1, limit: 20 } });
const farm = await client.farms.createFarm({ body: { name: 'My Farm', location: 'Kano' } });

API Modules

Authentication

• POST /auth/login - Login with email and password
• POST /auth/signup - Register new user
• POST /auth/google/initiate - Initiate Google OAuth flow
• POST /auth/google/callback - Handle Google OAuth callback
• POST /auth/refresh - Refresh access token
• POST /auth/logout - Logout user
• POST /auth/password/reset-request - Request password reset
• POST /auth/password/reset - Reset password with token
• POST /auth/password/change - Change password (authenticated)
• POST /auth/email/verify - Verify email address
• POST /auth/email/resend-verification - Resend verification email

Users

• GET /user/profile - Get current user profile
• PATCH /user/profile - Update user profile

Farms

• GET /farms - List farms
• POST /farms - Create farm
• GET /farms/:id - Get farm
• PATCH /farms/:id - Update farm
• DELETE /farms/:id - Delete farm

Fields

• GET /farms/:farmId/fields - List fields
• POST /farms/:farmId/fields - Create field
• GET /farms/:farmId/fields/:id - Get field
• PATCH /farms/:farmId/fields/:id - Update field
• DELETE /farms/:farmId/fields/:id - Delete field

Tasks

• GET /farms/:farmId/tasks - List tasks
• POST /farms/:farmId/tasks - Create task
• GET /farms/:farmId/tasks/:id - Get task
• PATCH /farms/:farmId/tasks/:id - Update task
• POST /farms/:farmId/tasks/:id/complete - Complete task
• DELETE /farms/:farmId/tasks/:id - Delete task
• POST /farms/:farmId/tasks/:id/notes - Add task note

Inventory

• GET /farms/:farmId/inventory - List inventory items
• POST /farms/:farmId/inventory - Create inventory item
• GET /farms/:farmId/inventory/:id - Get inventory item
• PATCH /farms/:farmId/inventory/:id - Update inventory item
• DELETE /farms/:farmId/inventory/:id - Delete inventory item
• POST /farms/:farmId/inventory/purchase - Log purchase

Finance

• Budget: GET, POST, PATCH, DELETE /farms/:farmId/budget
• Expenses: GET, POST, PATCH, DELETE /farms/:farmId/expenses
• Revenue: GET, POST, PATCH, DELETE /farms/:farmId/revenue
• GET /farms/:farmId/finance/summary - Finance summary

Harvest

• GET /farms/:farmId/harvests - List harvests
• POST /farms/:farmId/harvests - Create harvest
• GET /farms/:farmId/harvests/:id - Get harvest
• PATCH /farms/:farmId/harvests/:id - Update harvest
• DELETE /farms/:farmId/harvests/:id - Delete harvest

Soil Tests

• GET /farms/:farmId/soil-tests - List soil tests
• POST /farms/:farmId/soil-tests - Create soil test
• GET /farms/:farmId/soil-tests/:id - Get soil test
• PATCH /farms/:farmId/soil-tests/:id - Update soil test
• DELETE /farms/:farmId/soil-tests/:id - Delete soil test

Weather

• GET /farms/:farmId/weather - Get weather data

Team

• GET /farms/:farmId/team - List team members
• POST /farms/:farmId/team - Create team member
• GET /farms/:farmId/team/:id - Get team member
• PATCH /farms/:farmId/team/:id - Update team member
• DELETE /farms/:farmId/team/:id - Delete team member

Equipment

• GET /farms/:farmId/equipment - List equipment
• POST /farms/:farmId/equipment - Create equipment
• GET /farms/:farmId/equipment/:id - Get equipment
• PATCH /farms/:farmId/equipment/:id - Update equipment
• DELETE /farms/:farmId/equipment/:id - Delete equipment
• POST /farms/:farmId/equipment/:id/maintenance - Add maintenance record

Documents

• GET /farms/:farmId/documents - List documents
• POST /farms/:farmId/documents - Create document
• GET /farms/:farmId/documents/:id - Get document
• PATCH /farms/:farmId/documents/:id - Update document
• DELETE /farms/:farmId/documents/:id - Delete document

Suppliers

• Suppliers: GET, POST, PATCH, DELETE /farms/:farmId/suppliers
• Buyers: GET, POST, PATCH, DELETE /farms/:farmId/buyers

Analytics

• GET /farms/:farmId/analytics - Get analytics data

Common Features

Pagination

Most list endpoints support pagination:

{
  page?: number;  // Default: 1
  limit?: number; // Default: 20, Max: 100
}

Date Range Filtering

Many endpoints support date range filtering:

{
  startDate?: string; // ISO datetime
  endDate?: string;   // ISO datetime
}

GeoJSON Support

Farms and fields support GeoJSON geometry for boundaries:

{
  type: 'Polygon' | 'MultiPolygon' | 'Point' | 'LineString';
  coordinates: number[][][] | number[][] | number[];
}

Error Responses

All endpoints return standardized error responses:

{
  message: string;
  code?: string;
  errors?: Array<{
    field?: string;
    message: string;
  }>;
}

Type Safety

All schemas export TypeScript types:

import type {
  FarmResponse,
  CreateFarmInput,
  FieldResponse,
  TaskResponse,
  // ... etc
} from '@farmpro/contracts';

Development

Building

npm run build

Type Checking

npm run type-check

Publishing

npm run prepublishOnly  # Builds and validates
npm publish

License

ISC