Developers API

Manage real-estate developers. All endpoints below require authentication and role-based authorization.

Base URL: /api/developers

Authentication & Authorization

• Authentication: JWT token set as an HttpOnly cookie named token.
• Authorization (router-level): authorize(["admin", "sales", "finance", "agent"]) is applied to all routes in this router.
• Some actions may be logically admin-only in many systems, but this router currently allows all listed roles unless noted below.

Note: If the cookie is missing/invalid you will receive 401 Unauthorized. If the authenticated user lacks the required role(s) you will receive 403 Forbidden.

Resource Schema

A Developer represents the developer entity to whom projects may belong.

While the underlying schema may include more columns, responses in this router generally expose at least:

interface Developer {
  id: number;        // primary key
  name: string;      // developer display name
  company: number;   // owning company id (FK)
  // ...other server-managed fields may also be present (createdAt, updatedAt, isActive, etc.)
}

---

List Developers

Retrieve all developers visible to the requester.

Endpoint: GET /

Roles: admin, sales, finance, agent

Query Parameters: none

Response — 200 OK

[
  {
    "id": 12,
    "name": "Acme Developments",
    "company": 3
  },
  {
    "id": 13,
    "name": "Skyline Properties",
    "company": 3
  }
]

Errors

• 401 Unauthorized – missing/invalid auth cookie
• 500 Internal Server Error – unexpected error while fetching developers

cURL

curl -X GET \
  -b "token=<JWT>" \
  https://<host>/api/developers

---

Get Developers by Company

Retrieve all developers for a specific company id.

Endpoint: GET /:companyId

Roles: admin, sales, finance, agent

Path Parameters

• companyId (number, required) — company identifier

Response — 200 OK

[
  { "id": 21, "name": "Marina DevCo", "company": 7 },
  { "id": 22, "name": "Palm Estates", "company": 7 }
]

Errors

• 401 Unauthorized
• 500 Internal Server Error

cURL

curl -X GET \
  -b "token=<JWT>" \
  https://<host>/api/developers/7

---

Get Developer by ID

Fetch a single developer by id.

Endpoint: GET /single/:id

Roles: admin, sales, finance, agent

Path Parameters

• id (number, required) — developer id

Response — 200 OK

Note: The current implementation returns an array (with 0 or 1 element) rather than a single object.

[
  {
    "id": 12,
    "name": "Acme Developments",
    "company": 3
  }
]

If no developer exists with the provided id, an empty array is returned.

Errors

• 401 Unauthorized
• 500 Internal Server Error

cURL

curl -X GET \
  -b "token=<JWT>" \
  https://<host>/api/developers/single/12

---

Create Developer

Create a new developer.

Endpoint: POST /

Roles: admin, sales, finance, agent

Request Body

{
  "name": "Acme Developments",
  "company": 3
}

• name (string, required)
• company (number, required)

Responses

• 201 Created

  { "message": "Developer created successfully" }
• 500 Internal Server Error — on failure to create

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -b "token=<JWT>" \
  -d '{"name":"Acme Developments","company":3}' \
  https://<host>/api/developers

---

Update Developer

Update an existing developer.

Endpoint: PUT /:id

Roles: admin, sales, finance, agent

Path Parameters

• id (number, required)

Request Body

{
  "name": "Acme Holdings",
  "company": 4
}

• name (string, optional)
• company (number, optional)

Responses

• 200 OK

  { "message": "Developer updated successfully" }
• 500 Internal Server Error

cURL

curl -X PUT \
  -H "Content-Type: application/json" \
  -b "token=<JWT>" \
  -d '{"name":"Acme Holdings","company":4}' \
  https://<host>/api/developers/12

---

Delete Developer

Delete a developer by id.

Endpoint: DELETE /:id

Roles: admin, sales, finance, agent

Path Parameters

• id (number, required)

Responses

• 200 OK

  { "message": "Developer deleted successfully" }
• 500 Internal Server Error

cURL

curl -X DELETE \
  -b "token=<JWT>" \
  https://<host>/api/developers/12

---

Status Codes Summary

Code	Meaning
200	Success
201	Created
400	Bad Request (e.g., invalid body; not explicitly returned by current handlers)
401	Unauthorized
403	Forbidden
404	Not Found (some handlers return empty arrays instead)
500	Internal Server Error

Notes & Gotchas

• GET /single/:id returns an array (0 or 1 element), not a single object.
• The router is protected for roles: admin, sales, finance, agent. Super-admins also pass via policy upstream.
• The service does not currently validate payload shapes or types beyond basic use; ensure company is numeric.
• Timestamps/metadata may be present depending on your DB schema/migrations.