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

``bash
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

$3

`typescript
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
});
}
}
`

$3

`typescript
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

$3


- 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

$3

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

$3

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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

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

$3

- 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

$3

- 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

$3

- 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

$3

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

$3

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

Common Features

$3

Most list endpoints support pagination:
`typescript
{
page?: number; // Default: 1
limit?: number; // Default: 20, Max: 100
}
`

$3

Many endpoints support date range filtering:
`typescript
{
startDate?: string; // ISO datetime
endDate?: string; // ISO datetime
}
`

$3

Farms and fields support GeoJSON geometry for boundaries:
`typescript
{
type: 'Polygon' | 'MultiPolygon' | 'Point' | 'LineString';
coordinates: number[][][] | number[][] | number[];
}
`

$3

All endpoints return standardized error responses:
`typescript
{
message: string;
code?: string;
errors?: Array<{
field?: string;
message: string;
}>;
}
`

Type Safety

All schemas export TypeScript types:

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

Development

$3

`bash
npm run build
`

$3

`bash
npm run type-check
`

$3

`bash
npm run prepublishOnly # Builds and validates
npm publish
``

License

ISC