@deepintel-ltd/farmpro-contracts 1.0.1

package/README.md

@@ -0,0 +1,279 @@
+# FarmPro API Contracts
+
+Type-safe API contracts for FarmPro API using [ts-rest](https://ts-rest.com/) and [Zod](https://zod.dev/).
+
+## 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
+
+### Backend (NestJS)
+
+```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
+    });
+  }
+}
+```
+
+### Frontend
+
+```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
+
+### 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:
+```typescript
+{
+  page?: number;  // Default: 1
+  limit?: number; // Default: 20, Max: 100
+}
+```
+
+### Date Range Filtering
+Many endpoints support date range filtering:
+```typescript
+{
+  startDate?: string; // ISO datetime
+  endDate?: string;   // ISO datetime
+}
+```
+
+### GeoJSON Support
+Farms and fields support GeoJSON geometry for boundaries:
+```typescript
+{
+  type: 'Polygon' | 'MultiPolygon' | 'Point' | 'LineString';
+  coordinates: number[][][] | number[][] | number[];
+}
+```
+
+### Error Responses
+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
+
+### Building
+
+```bash
+npm run build
+```
+
+### Type Checking
+
+```bash
+npm run type-check
+```
+
+### Publishing
+
+```bash
+npm run prepublishOnly  # Builds and validates
+npm publish
+```
+
+## License
+
+ISC
+

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@deepintel-ltd/farmpro-contracts",
+  "version": "1.0.1",
+  "description": "Type-safe API contracts for FarmPro API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "type-check": "tsc --noEmit",
+    "validate": "npm run type-check"
+  },
+  "keywords": [
+    "api",
+    "contracts",
+    "typescript",
+    "zod",
+    "ts-rest",
+    "agriculture",
+    "farming",
+    "farmpro"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@ts-rest/core": "^3.52.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@ts-rest/core": "^3.52.0",
+    "zod": "^3.25.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}