feat: openapi for stock option endpoint

src/server/api/index.ts

@@ -3,6 +3,7 @@ import { middlewareServices } from "./middlewares/services";
 import { registerCompanyRoutes } from "./routes/company";
 import { registerShareRoutes } from "./routes/share";
 import { registerStakeholderRoutes } from "./routes/stakeholder";
+import { registerOptionRoutes } from "./routes/stock-option";
 
 const api = PublicAPI();
 
@@ -12,5 +13,6 @@ api.use("*", middlewareServices());
 registerCompanyRoutes(api);
 registerShareRoutes(api);
 registerStakeholderRoutes(api);
+registerOptionRoutes(api);
 
 export default api;

src/server/api/routes/stock-option/create.ts

@@ -0,0 +1,146 @@
+import { generatePublicId } from "@/common/id";
+import {
+  CreateOptionSchema,
+  type TOptionSchema,
+} from "@/server/api/schema/option";
+import {
+  authMiddleware,
+  withAuthApiV1,
+} from "@/server/api/utils/endpoint-creator";
+import { Audit } from "@/server/audit";
+import { z } from "@hono/zod-openapi";
+
+type AuditPromise = ReturnType<typeof Audit.create>;
+
+const ResponseSchema = z.object({
+  message: z.string(),
+  data: CreateOptionSchema,
+});
+
+const ParamsSchema = z.object({
+  companyId: z.string().openapi({
+    param: {
+      name: "companyId",
+      in: "path",
+    },
+    description: "Company ID",
+    type: "string",
+    example: "clxwbok580000i7nge8nm1ry0",
+  }),
+});
+
+export const create = withAuthApiV1
+  .createRoute({
+    method: "post",
+    path: "/v1/{companyId}/options",
+    summary: "Create options",
+    description: "Issue options to a stakeholder in a company.",
+    tags: ["Options"],
+    middleware: [authMiddleware()],
+    request: {
+      params: ParamsSchema,
+      body: {
+        content: {
+          "application/json": {
+            schema: CreateOptionSchema,
+          },
+        },
+      },
+    },
+    responses: {
+      200: {
+        content: {
+          "application/json": {
+            schema: ResponseSchema,
+          },
+        },
+        description: "Confirmation of options issued with relevant details.",
+      },
+    },
+  })
+  .handler(async (c) => {
+    const { db, audit, client } = c.get("services");
+    const { membership } = c.get("session");
+    const { requestIp, userAgent } = client;
+
+    const { documents, ...rest } = c.req.valid("json");
+
+    const option = await db.$transaction(async (tx) => {
+      const option = await tx.option.create({
+        data: { ...rest, companyId: membership.companyId },
+      });
+
+      let auditPromises: AuditPromise[] = [];
+
+      if (documents && documents.length > 0) {
+        const bulkDocuments = documents.map((doc) => ({
+          companyId: membership.companyId,
+          uploaderId: membership.memberId,
+          publicId: generatePublicId(),
+          name: doc.name,
+          bucketId: doc.bucketId,
+          optionId: option.id,
+        }));
+
+        const docs = await tx.document.createManyAndReturn({
+          data: bulkDocuments,
+          skipDuplicates: true,
+          select: {
+            id: true,
+            name: true,
+          },
+        });
+
+        auditPromises = docs.map((doc) =>
+          Audit.create(
+            {
+              action: "document.created",
+              companyId: membership.companyId,
+              actor: { type: "user", id: membership.userId },
+              context: {
+                userAgent,
+                requestIp,
+              },
+              target: [{ type: "document", id: doc.id }],
+              summary: `${membership.user.name} created a document while issuing a stock option : ${doc.name}`,
+            },
+            tx,
+          ),
+        );
+      }
+
+      auditPromises.push(
+        audit.create(
+          {
+            action: "option.created",
+            companyId: membership.companyId,
+            actor: { type: "user", id: membership.userId },
+            context: {
+              userAgent,
+              requestIp,
+            },
+            target: [{ type: "option", id: option.id }],
+            summary: `${membership.user.name} added option for stakeholder ${option.stakeholderId}`,
+          },
+          tx,
+        ),
+      );
+
+      await Promise.all(auditPromises);
+
+      return option;
+    });
+
+    const data: TOptionSchema = {
+      ...option,
+      createdAt: option.createdAt.toISOString(),
+      updatedAt: option.updatedAt.toISOString(),
+      issueDate: option.issueDate.toISOString(),
+      expirationDate: option.expirationDate.toISOString(),
+      rule144Date: option.rule144Date.toISOString(),
+      vestingStartDate: option.vestingStartDate.toISOString(),
+      boardApprovalDate: option.boardApprovalDate.toISOString(),
+    };
+
+    return c.json({ message: "Option successfully created.", data }, 200);
+  });

src/server/api/routes/stock-option/delete.ts

@@ -0,0 +1,111 @@
+import { z } from "@hono/zod-openapi";
+import { ApiError } from "../../error";
+
+import { authMiddleware, withAuthApiV1 } from "../../utils/endpoint-creator";
+
+const ParamsSchema = z.object({
+  id: z.string().openapi({
+    param: {
+      name: "id",
+      in: "path",
+    },
+    description: "Option ID",
+    type: "string",
+    example: "clyabgufg004u5tbtnz0r4cax",
+  }),
+  companyId: z.string().openapi({
+    param: {
+      name: "companyId",
+      in: "path",
+    },
+    description: "Company ID",
+    type: "string",
+    example: "clxwbok580000i7nge8nm1ry0",
+  }),
+});
+
+const ResponseSchema = z.object({
+  message: z.string().openapi({
+    description:
+      "A text providing details about the API request result, including success, error, or warning messages.",
+  }),
+});
+
+export const deleteOne = withAuthApiV1
+  .createRoute({
+    method: "delete",
+    path: "/v1/{companyId}/options/{id}",
+    summary: "Delete a option",
+    description: "Remove an issued option by its ID.",
+    tags: ["Options"],
+    middleware: [authMiddleware()],
+    request: { params: ParamsSchema },
+    responses: {
+      200: {
+        content: {
+          "application/json": {
+            schema: ResponseSchema,
+          },
+        },
+        description: "Confirmation that the issued option has been removed.",
+      },
+    },
+  })
+  .handler(async (c) => {
+    const { db, audit, client } = c.get("services");
+    const { membership } = c.get("session");
+    const { requestIp, userAgent } = client as {
+      requestIp: string;
+      userAgent: string;
+    };
+
+    const { id } = c.req.valid("param");
+
+    await db.$transaction(async (tx) => {
+      const option = await tx.option.findUnique({
+        where: {
+          id,
+          companyId: membership.companyId,
+        },
+        select: {
+          id: true,
+          stakeholderId: true,
+        },
+      });
+
+      if (!option) {
+        throw new ApiError({
+          code: "NOT_FOUND",
+          message: `Option with ID ${id} not found`,
+        });
+      }
+
+      await tx.option.delete({
+        where: {
+          id: option.id,
+        },
+      });
+
+      await audit.create(
+        {
+          action: "option.deleted",
+          companyId: membership.companyId,
+          actor: { type: "user", id: membership.userId },
+          context: {
+            userAgent,
+            requestIp,
+          },
+          target: [{ type: "option", id }],
+          summary: `${membership.user.name} deleted the option for stakeholder ${option.stakeholderId}`,
+        },
+        tx,
+      );
+    });
+
+    return c.json(
+      {
+        message: "Option deleted successfully",
+      },
+      200,
+    );
+  });

src/server/api/routes/stock-option/getMany.ts

@@ -0,0 +1,84 @@
+import { OptionSchema } from "@/server/api/schema/option";
+import { z } from "@hono/zod-openapi";
+import {
+  PaginationQuerySchema,
+  PaginationResponseSchema,
+} from "../../schema/pagination";
+
+import { authMiddleware, withAuthApiV1 } from "../../utils/endpoint-creator";
+
+const ResponseSchema = z.object({
+  data: z.array(OptionSchema),
+  meta: PaginationResponseSchema,
+});
+
+const ParamsSchema = z.object({
+  companyId: z.string().openapi({
+    param: {
+      name: "companyId",
+      in: "path",
+    },
+    description: "Company ID",
+    type: "string",
+    example: "clxwbok580000i7nge8nm1ry0",
+  }),
+});
+
+export const getMany = withAuthApiV1
+  .createRoute({
+    summary: "List options",
+    description: "Retrieve a list of issued options for the company.",
+    tags: ["Options"],
+    method: "get",
+    path: "/v1/{companyId}/options",
+    middleware: [authMiddleware()],
+    request: {
+      params: ParamsSchema,
+      query: PaginationQuerySchema,
+    },
+    responses: {
+      200: {
+        content: {
+          "application/json": {
+            schema: ResponseSchema,
+          },
+        },
+        description: "A list of issued options with their details.",
+      },
+    },
+  })
+  .handler(async (c) => {
+    const { membership } = c.get("session");
+    const { db } = c.get("services");
+    const query = c.req.valid("query");
+
+    // To get rid of parseCursor in each getMany route
+    //@TODO(Better to have parsing at server/db in root )
+    const [data, meta] = await db.option
+      .paginate({ where: { companyId: membership.companyId } })
+      .withCursor({
+        limit: query.limit,
+        after: query.cursor,
+        getCursor({ id }) {
+          return id;
+        },
+        parseCursor(cursor) {
+          return { id: cursor };
+        },
+      });
+
+    const response: z.infer<typeof ResponseSchema> = {
+      meta,
+      data: data.map((i) => ({
+        ...i,
+        createdAt: i.createdAt.toISOString(),
+        updatedAt: i.updatedAt.toISOString(),
+        issueDate: i.issueDate.toISOString(),
+        expirationDate: i.expirationDate.toISOString(),
+        rule144Date: i.rule144Date.toISOString(),
+        vestingStartDate: i.vestingStartDate.toISOString(),
+        boardApprovalDate: i.boardApprovalDate.toISOString(),
+      })),
+    };
+    return c.json(response, 200);
+  });