refactor: add type helpers and build new type paradigm

Update ActivityContact, Permit, and Note types

Author: kyle1morel

frontend/src/components/authorization/AuthorizationForm.vue

@@ -24,7 +24,7 @@ import { notInFutureValidator } from '@/validators/common';
 import type { Ref } from 'vue';
 import type { Permit, PermitTracking, PermitType, SourceSystemKind, User } from '@/types';
 import type { IStamps } from '@/interfaces';
-import type { PermitArgs } from '@/types/Permit';
+import type { PermitUpsertArgs } from '@/types/models';
 
 // Props
 const { authorization = undefined, editable } = defineProps<{
@@ -269,7 +269,8 @@ function onDelete() {
     rejectProps: { outlined: true },
     accept: async () => {
       try {
-        await permitService.deletePermit(authorization?.permitId as string);
+        if (!authorization) throw new Error('No authorization');
+        await permitService.deletePermit({ permitId: authorization.permitId });
         toast.success(t('authorization.authorizationForm.authDeleted'));
         if (!projectRouteName?.value) throw new Error('No route');
         router.push({
@@ -300,7 +301,7 @@ async function onSubmit(data: GenericObject) {
   const statusLastVerified = splitDateTime(data.statusLastVerified);
 
   const { authorizationType, permitNote, ...rest } = data as FormSchemaType;
-  const permitData: PermitArgs = {
+  const permitData: PermitUpsertArgs = {
     ...rest,
     activityId: getProject.value!.activityId,
     permitTypeId: authorizationType.permitTypeId,

frontend/src/components/enquiry/EnquiryForm.vue

@@ -302,11 +302,11 @@ const onSubmit = async (values: GenericObject) => {
     if (primaryContact.value?.contactId !== values.contact.contactId) {
       const newContact = (await contactService.updateContact(values.contact)).data;
       if (newContact.contactId) {
-        await activityContactService.createActivityContact(
-          enquiry.activityId,
-          newContact.contactId,
-          ActivityContactRole.PRIMARY
-        );
+        await activityContactService.createActivityContact({
+          activityId: enquiry.activityId,
+          contactId: newContact.contactId,
+          role: ActivityContactRole.PRIMARY
+        });
 
         setBasicInfo(newContact);
       }

frontend/src/components/projectCommon/ProjectTeamTab.vue

@@ -124,7 +124,11 @@ async function onAddUsers(contactsAndRoles: { contact: Contact; role: ActivityCo
       if (!getProject.value?.activityId) throw new Error('No activity ID');
 
       const response = (
-        await activityContactService.createActivityContact(getProject.value.activityId, contact.contactId, role)
+        await activityContactService.createActivityContact({
+          activityId: getProject.value.activityId,
+          contactId: contact.contactId,
+          role
+        })
       ).data;
 
       // Update store
@@ -162,7 +166,11 @@ async function onManageUser(contact: ActivityContact, role: ActivityContactRole)
     if (!getProject.value?.activityId) throw new Error('No activity ID');
 
     const { updated, demoted } = (
-      await activityContactService.updateActivityContact(getProject.value.activityId, contact.contactId, role)
+      await activityContactService.updateActivityContact({
+        activityId: getProject.value.activityId,
+        contactId: contact.contactId,
+        role
+      })
     ).data;
 
     // Update store
@@ -212,7 +220,10 @@ async function onRevokeUser(contact: ActivityContact) {
   try {
     if (!getProject.value?.activityId) throw new Error('No activity ID');
 
-    await activityContactService.deleteActivityContact(getProject.value.activityId, contact.contactId);
+    await activityContactService.deleteActivityContact({
+      activityId: getProject.value.activityId,
+      contactId: contact.contactId
+    });
 
     // Update store
     projectStore.removeActivityContact(contact);

frontend/src/interfaces/IProject.ts

@@ -1,5 +1,5 @@
 import type { IStamps } from '@/interfaces';
-import type { Activity } from '@/types/Activity';
+import type { Activity } from '@/types/models';
 import type { Contact } from '@/types/Contact';
 import type { User } from '@/types/User';
 import type { ApplicationStatus, SubmissionType } from '@/utils/enums/projectCommon';

frontend/src/services/activityContactService.ts

@@ -2,41 +2,59 @@ import { appAxios } from './interceptors';
 
 import type { AxiosResponse } from 'axios';
 import type { ActivityContact } from '@/types';
+import type {
+  ActivityContactCreateArgs,
+  ActivityContactDeleteArgs,
+  ActivityContactUpdateArgs
+} from '@/types/ActivityContact';
 
-export default {
-  /**
-   * @function listActivityContacts
-   * @returns {Promise} An axios response
-   */
-  createActivityContact(activityId: string, contactId: string, role: string): Promise<AxiosResponse<ActivityContact>> {
-    return appAxios().post(`activity/${activityId}/contact/${contactId}`, { role });
-  },
+/**
+ * Create an Activity Contact
+ * @param args - DTO containing path params and fields
+ * @returns Axios response with the created ActivityContact
+ */
+export function createActivityContact(args: ActivityContactCreateArgs): Promise<AxiosResponse<ActivityContact>> {
+  const { activityId, contactId, ...body } = args;
+  return appAxios().post(`activity/${activityId}/contact/${contactId}`, body);
+}
 
-  /**
-   * @function deleteActivityContacts
-   * @returns {Promise} An axios response
-   */
-  deleteActivityContact(activityId: string, contactId: string): Promise<AxiosResponse<ActivityContact>> {
-    return appAxios().delete(`activity/${activityId}/contact/${contactId}`);
-  },
+/**
+ * Delete an Activity Contact
+ * @param args - DTO containing the compound key for deletion
+ * @returns Axios response with the deleted ActivityContact
+ */
+export function deleteActivityContact(args: ActivityContactDeleteArgs): Promise<AxiosResponse<ActivityContact>> {
+  const { activityId, contactId } = args;
+  return appAxios().delete(`activity/${activityId}/contact/${contactId}`);
+}
 
-  /**
-   * @function listActivityContacts
-   * @returns {Promise} An axios response
-   */
-  listActivityContacts(activityId: string): Promise<AxiosResponse<ActivityContact[]>> {
-    return appAxios().get(`activity/${activityId}/contact`);
-  },
+/**
+ * List Activity Contact for a specific activity
+ * @param activityId - ID of the activity to list contacts for
+ * @returns Axios response with an array of ActivityContacts
+ */
+export function listActivityContacts(activityId: string): Promise<AxiosResponse<ActivityContact[]>> {
+  return appAxios().get(`activity/${activityId}/contact`);
+}
 
-  /**
-   * @function updateActivityContact
-   * @returns {Promise} An axios response
-   */
-  updateActivityContact(
-    activityId: string,
-    contactId: string,
-    role: string
-  ): Promise<AxiosResponse<{ updated: ActivityContact; demoted: ActivityContact | undefined }>> {
-    return appAxios().put(`activity/${activityId}/contact/${contactId}`, { role });
-  }
+/**
+ * Update an Activity Contact
+ * @param args - DTO containing path params and updatable fields
+ * @returns Axios response containing updated and optionally demoted ActivityContact
+ */
+export function updateActivityContact(
+  args: ActivityContactUpdateArgs
+): Promise<AxiosResponse<{ updated: ActivityContact; demoted: ActivityContact | undefined }>> {
+  const { activityId, contactId, ...body } = args;
+  return appAxios().put(`activity/${activityId}/contact/${contactId}`, body);
+}
+
+/** Hybrid default export object for backward compatibility */
+const activityService = {
+  createActivityContact,
+  updateActivityContact,
+  deleteActivityContact,
+  listActivityContacts
 };
+
+export default activityService;

frontend/src/services/permitService.ts

@@ -1,50 +1,72 @@
 import { appAxios } from './interceptors';
 import { useAppStore } from '@/store';
 
-import type { ListPermitsOptions, Permit } from '@/types';
-import type { Initiative } from '@/utils/enums/application';
+import type { AxiosResponse } from 'axios';
+import type { ListPermitsOptions, Permit, PermitType } from '@/types';
+import type { PermitDeleteArgs, PermitUpsertArgs } from '@/types/models';
 
 const PATH = 'permit';
 
-export default {
-  /**
-   * @function deletePermit
-   * @returns {Promise} An axios response
-   */
-  deletePermit(permitId: string) {
-    return appAxios().delete(`${useAppStore().getInitiative.toLowerCase()}/${PATH}/${permitId}`);
-  },
-
-  /**
-   * @function getPermit
-   * @returns {Promise} An axios response
-   */
-  getPermit(permitId: string) {
-    return appAxios().get(`${useAppStore().getInitiative.toLowerCase()}/${PATH}/${permitId}`);
-  },
-
-  /**
-   * @function getPermitTypes
-   * @param {Initiative} initiative Initiative type to get permit types for
-   * @returns {Promise} An axios response
-   */
-  getPermitTypes(initiative: Initiative) {
-    return appAxios().get(`${useAppStore().getInitiative.toLowerCase()}/${PATH}/types`, { params: { initiative } });
-  },
-
-  /**
-   * @function listPermits
-   * @returns {Promise} An axios response
-   */
-  async listPermits(options?: ListPermitsOptions) {
-    return appAxios().get(`${useAppStore().getInitiative.toLowerCase()}/${PATH}`, { params: options });
-  },
-
-  /**
-   * @function upsertPermit
-   * @returns {Promise} An axios response
-   */
-  upsertPermit(data: Permit) {
-    return appAxios().put(`${useAppStore().getInitiative.toLowerCase()}/${PATH}`, data);
-  }
+/** Helper to get initiative-prefixed base URL */
+function getBaseUrl(): string {
+  return `${useAppStore().getInitiative.toLowerCase()}/${PATH}`;
+}
+
+/**
+ * Delete a Permit
+ * @param data - DTO containing permitId
+ * @returns Axios response with the deleted Permit
+ */
+export function deletePermit(data: PermitDeleteArgs): Promise<AxiosResponse<Permit>> {
+  const { permitId } = data;
+  return appAxios().delete(`${getBaseUrl()}/${permitId}`);
+}
+
+/**
+ * Get a single Permit by ID
+ * @param permitId - ID of the permit to fetch
+ * @returns Axios response with the Permit
+ */
+export function getPermit(permitId: string): Promise<AxiosResponse<Permit>> {
+  return appAxios().get(`${getBaseUrl()}/${permitId}`);
+}
+
+/**
+ * Get Permit types for a given initiative
+ * @param initiative - Initiative type
+ * @returns Axios response with permit types
+ */
+export function getPermitTypes(initiative: string): Promise<AxiosResponse<PermitType[]>> {
+  return appAxios().get(`${useAppStore().getInitiative.toLowerCase()}/${PATH}/types`, {
+    params: { initiative }
+  });
+}
+
+/**
+ * List Permits with optional filters
+ * @param options - Optional query parameters for listing
+ * @returns Axios response with an array of Permits
+ */
+export function listPermits(options?: ListPermitsOptions): Promise<AxiosResponse<Permit[]>> {
+  return appAxios().get(getBaseUrl(), { params: options });
+}
+
+/**
+ * Upsert (create or update) a Permit
+ * @param data - Full Permit object
+ * @returns Axios response with the upserted Permit
+ */
+export function upsertPermit(data: PermitUpsertArgs): Promise<AxiosResponse<Permit>> {
+  return appAxios().put(getBaseUrl(), data);
+}
+
+/** Hybrid default export object for backward compatibility */
+const permitService = {
+  upsertPermit,
+  deletePermit,
+  getPermit,
+  listPermits,
+  getPermitTypes
 };
+
+export default permitService;

frontend/src/types/Activity.ts

@@ -1,12 +1,17 @@
 import type { IStamps } from '@/interfaces';
 import type { Contact } from '@/types';
 import type { ActivityContactRole } from '@/utils/enums/projectCommon';
+import type { CreateDTO, DeleteDTO, PutDTO } from './helpers';
 
-export type ActivityContact = {
+export interface ActivityContact extends IStamps {
   activityId: string;
   contactId: string;
   role: ActivityContactRole;
-
-  // Joined
   contact?: Contact;
-} & Partial<IStamps>;
+}
+
+type ActivityContactExcludedKeys = 'contact';
+
+export type ActivityContactCreateArgs = CreateDTO<ActivityContact, ActivityContactExcludedKeys>;
+export type ActivityContactDeleteArgs = DeleteDTO<ActivityContact, ['activityId', 'contactId']>;
+export type ActivityContactUpdateArgs = PutDTO<ActivityContact, ActivityContactExcludedKeys>;