Implement listNested pattern for entity-api

Author: jhodapp

src/lib/api/coaching-sessions.ts

@@ -130,6 +130,28 @@ export const CoachingSessionApi = {
     throw new Error("Delete nested operation not implemented");
   },
 
+  /**
+   * Lists coaching sessions nested under a user (follows the createNested pattern).
+   *
+   * This uses the /users/{user_id}/coaching_sessions endpoint with support for
+   * query parameters like date filtering and related resource inclusion.
+   *
+   * @param userId The ID of the user (coach or coachee)
+   * @param params Query parameters for filtering, sorting, and including related data
+   * @returns Promise resolving to array of EnrichedCoachingSession objects
+   */
+  listNested: async (
+    userId: Id,
+    params?: any
+  ): Promise<EnrichedCoachingSession[]> => {
+    return EntityApi.listNestedFn<EnrichedCoachingSession>(
+      USERS_BASEURL,
+      userId,
+      'coaching_sessions',
+      params
+    );
+  },
+
   /**
    * Fetches coaching sessions for a specific user with optional related data.
    *
@@ -168,10 +190,7 @@ export const CoachingSessionApi = {
       params.sort_order = sortOrder;
     }
 
-    return EntityApi.listFn<EnrichedCoachingSession>(
-      `${USERS_BASEURL}/${userId}/coaching_sessions`,
-      { params }
-    );
+    return CoachingSessionApi.listNested(userId, { params });
   },
 };
 

src/lib/api/entity-api.ts

@@ -26,6 +26,7 @@ export namespace EntityApi {
   interface ApiOperations<T, U> {
     create?: (entity: T) => Promise<U>;
     createNested?: (id: Id, entity: T) => Promise<U>;
+    listNested?: (id: Id, params?: any) => Promise<U[]>;
     update?: (id: Id, entity: T) => Promise<U>;
     delete?: (id: Id) => Promise<U>;
     deleteNested?: (entityId: Id, nestedEntityId: Id) => Promise<U>;
@@ -161,6 +162,43 @@ export namespace EntityApi {
     );
   };
 
+  /**
+   * Fetches a list of entities nested under a parent entity.
+   * Constructs the URL using the parent entity's ID and base URL pattern.
+   *
+   * @template R The raw entity type returned by the API
+   * @template U The transformed entity type (defaults to R if no transform provided)
+   * @param baseUrl The base URL pattern (e.g., "/users")
+   * @param id The parent entity's ID
+   * @param resourcePath The nested resource path (e.g., "coaching_sessions")
+   * @param params Optional query parameters to include in the request
+   * @param transform Optional transformation function applied to each entity in the response
+   * @returns A Promise resolving to an array of entities of type U
+   *
+   * @remarks This function:
+   * - Builds URLs for nested resources following RESTful patterns
+   * - Follows the same pattern as createNested for consistency
+   * - Handles both raw and transformed data workflows
+   * - Maintains type safety through generic parameters
+   */
+  export const listNestedFn = async <R, U = R>(
+    baseUrl: string,
+    id: Id,
+    resourcePath: string,
+    params: any,
+    transform?: (item: R) => U
+  ): Promise<U[]> => {
+    if (!params) {
+      return []; // Return empty array if params are null
+    }
+
+    return fetcher<R[], U[]>(
+      `${baseUrl}/${id}/${resourcePath}`,
+      params,
+      transform ? (data) => data.map(transform) : undefined
+    );
+  };
+
   /**
    * Fetches a single entity from the specified URL.
    *
@@ -452,6 +490,15 @@ export namespace EntityApi {
        */
       createNested: (id: Id, entity: T) =>
         executeWithState(() => api.createNested!(id, entity)),
+      /**
+       * Lists entities nested under a parent entity (foreign key relationship).
+       *
+       * @param id The parent entity's id under which to list entities
+       * @param params Optional query parameters for filtering and sorting
+       * @returns Promise resolving to an array of entities
+       */
+      listNested: (id: Id, params?: any) =>
+        executeWithState(() => api.listNested!(id, params)),
       /**
        * Updates an existing entity.
        *