feat: getting started with paginated api to getMany stakeholder

src/server/api/index.ts

@@ -1,5 +1,6 @@
 import { PublicAPI } from "./hono";
 import companyRoutes from "./routes/company";
+import stakeholderRoutes from "./routes/company/stakeholder";
 import teamRoutes from "./routes/company/team";
 
 export const api = PublicAPI();
@@ -10,4 +11,7 @@ companyRoutes(api);
 // RESTful routes for a team in a company
 teamRoutes(api);
 
+// RESTful routes for a stakeholder in a company
+stakeholderRoutes(api);
+
 export default api;

src/server/api/routes/company/stakeholder/getMany.ts

@@ -0,0 +1,71 @@
+import { ErrorResponses } from "@/server/api/error";
+import type { PublicAPI } from "@/server/api/hono";
+import {
+  PaginationQuerySchema,
+  PaginationResponseSchema,
+} from "@/server/api/schema/pagination";
+import { StakeholderApiSchema } from "@/server/api/schema/stakeholder";
+import { createRoute, z } from "@hono/zod-openapi";
+import type { Context, HonoRequest } from "hono";
+
+const RequestParamsSchema = z.object({
+  id: z
+    .string()
+    .cuid()
+    .openapi({
+      description: "Company ID",
+      param: {
+        name: "id",
+        in: "path",
+      },
+
+      example: "clxwbok580000i7nge8nm1ry0",
+    }),
+});
+
+const ResponseSchema = z.object({
+  data: StakeholderApiSchema,
+  meta: PaginationResponseSchema,
+});
+
+const route = createRoute({
+  method: "get",
+  path: "/v1/companies/:id/stakeholders",
+  request: {
+    query: PaginationQuerySchema,
+    params: RequestParamsSchema,
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: ResponseSchema,
+        },
+      },
+      description: "Get a paginated list of stakeholders for a company.",
+    },
+
+    ...ErrorResponses,
+  },
+});
+
+const getMany = (app: PublicAPI) => {
+  app.openapi(route, async (c: Context) => {
+    const req: HonoRequest = await c.req;
+    // const { id } = req.params;
+
+    // TODO : Implement the logic to fetch stakeholders from the database, please take a look at this doc for reference: https://www.prisma.io/docs/concepts/components/prisma-client/crud
+    // https://www.prisma.io/docs/orm/prisma-client/queries/pagination#cursor-based-pagination
+
+    // return c.json({
+    //   data: [],
+    //   meta: {
+    //     count: 0,
+    //     total: 0,
+    //     cursor: null,
+    //   },
+    // });
+  });
+};
+
+export default getMany;

src/server/api/routes/company/stakeholder/index.ts

@@ -1,16 +1,16 @@
 import type { PublicAPI } from "@/server/api/hono";
-import create from "./create";
-import delete_ from "./delete";
+// import create from "./create";
+// import delete from "./delete";
 import getMany from "./getMany";
-import getOne from "./getOne";
-import update from "./update";
+// import getOne from "./getOne";
+// import update from "./update";
 
 const stakeholderRoutes = (api: PublicAPI) => {
-  getOne(api);
+  // getOne(api);
   getMany(api);
-  create(api);
-  update(api);
-  delete_(api);
+  // create(api);
+  // update(api);
+  // delete(api);
 };
 
 export default stakeholderRoutes;

src/server/api/schema/pagination.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+
+export const PaginationQuerySchema = z.object({
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .openapi({
+      description: "Number of items to take",
+      param: {
+        name: "take",
+        in: "query",
+      },
+      example: 10,
+      default: 50,
+      maximum: 50,
+    }),
+
+  cursor: z
+    .string()
+    .optional()
+    .openapi({
+      description: "Cursor for the next page",
+      param: {
+        name: "cursor",
+        in: "query",
+      },
+      example: "cly151kxq0000i7ngb3erchgo", // CUID of the last item
+    }),
+});
+
+export const PaginationResponseSchema = z.object({
+  count: z.number().int().positive().openapi({
+    description: "Number of records returned",
+    example: 50,
+  }),
+
+  total: z.number().int().positive().openapi({
+    description: "Total number of records",
+    example: 100,
+  }),
+
+  cursor: z.string().optional().openapi({
+    description: "Next page cursor",
+    example: "cly151kxq0000i7ngb3erchgo",
+  }),
+});

src/server/api/schema/stakeholder.ts

@@ -0,0 +1,80 @@
+import {
+  StakeholderRelationshipEnum,
+  StakeholderTypeEnum,
+} from "@prisma/client";
+import { z } from "zod";
+
+const StakeholderTypeArray = Object.values(StakeholderTypeEnum) as [
+  string,
+  ...string[],
+];
+const StakeholderRelationshipArray = Object.values(
+  StakeholderRelationshipEnum,
+) as [string, ...string[]];
+
+export const StakeholderApiSchema = z.object({
+  id: z.string().cuid().openapi({
+    description: "Stakeholder ID",
+    example: "cly13ipa40000i7ng42mv4x7b",
+  }),
+
+  name: z.string().openapi({
+    description: "Stakeholder name",
+    example: "John Doe",
+  }),
+
+  email: z.string().email().openapi({
+    description: "Stakeholder email",
+    example: "[email protected]",
+  }),
+
+  institutionName: z.string().optional().openapi({
+    description: "Institution name",
+    example: "ACME Corp",
+  }),
+
+  stakeholderType: z.enum(StakeholderTypeArray).openapi({
+    description: "Stakeholder type",
+    example: "INDIVIDUAL",
+  }),
+
+  currentRelationship: z.enum(StakeholderRelationshipArray).openapi({
+    description: "Current relationship with the company",
+    example: "EMPLOYEE",
+  }),
+
+  streetAddress: z.string().optional().openapi({
+    description: "Street address",
+    example: "123 Main St",
+  }),
+
+  city: z.string().optional().openapi({
+    description: "City",
+    example: "San Francisco",
+  }),
+
+  state: z.string().optional().openapi({
+    description: "State",
+    example: "CA",
+  }),
+
+  zipcode: z.string().optional().openapi({
+    description: "Zip code",
+    example: "94105",
+  }),
+
+  country: z.string().optional().openapi({
+    description: "Country",
+    example: "USA",
+  }),
+
+  createdAt: z.string().date().openapi({
+    description: "Date the stakeholder was created",
+    example: "2022-01-01T00:00:00Z",
+  }),
+
+  updatedAt: z.string().date().openapi({
+    description: "Date the stakeholder was last updated",
+    example: "2022-01-01T00:00:00Z",
+  }),
+});