feat: add songViewBasic schema and getArtistListeners endpoint with associated types

apps/api/lexicons/artist/defs.json

···
         }
       }
     },
+    "songViewBasic": {
+      "type": "object",
+      "properties": {
+        "uri": {
+          "type": "string",
+          "description": "The URI of the song.",
+          "format": "at-uri"
+        },
+        "title": {
+          "type": "string",
+          "description": "The title of the song."
+        },
+        "playCount": {
+          "type": "integer",
+          "description": "The number of times the song has been played.",
+          "minimum": 0
+        }
+      }
+    },
     "listenerViewBasic": {
       "type": "object",
       "properties": {
···
         },
         "mostListenedSong": {
           "type": "ref",
-          "ref": "app.rocksky.song.defs#songViewBasic"
+          "ref": "app.rocksky.artist.defs#songViewBasic"
+        },
+        "totalPlays": {
+          "type": "integer",
+          "description": "The total number of plays by the listener.",
+          "minimum": 0
+        },
+        "rank": {
+          "type": "integer",
+          "description": "The rank of the listener among all listeners of the artist.",
+          "minimum": 1
         }
       }
     }

apps/api/pkl/defs/artist/defs.pkl

···
     }
   }
 
+  ["songViewBasic"] {
+    type = "object"
+    properties {
+      ["uri"] = new StringType {
+        type = "string"
+        format = "at-uri"
+        description = "The URI of the song."
+      }
+
+      ["title"] = new StringType {
+        type = "string"
+        description = "The title of the song."
+      }
+
+      ["playCount"] = new IntegerType {
+        type = "integer"
+        description = "The number of times the song has been played."
+        minimum = 0
+      }
+
+    }
+  }
+
   ["listenerViewBasic"] {
     type = "object"
     properties {
···
       }
 
       ["mostListenedSong"] = new Ref {
-        ref = "app.rocksky.song.defs#songViewBasic"
+        ref = "app.rocksky.artist.defs#songViewBasic"
+      }
+
+      ["totalPlays"] = new IntegerType {
+        type = "integer"
+        description = "The total number of plays by the listener."
+        minimum = 0
+      }
+
+      ["rank"] = new IntegerType {
+        type = "integer"
+        description = "The rank of the listener among all listeners of the artist."
+        minimum = 1
       }
 
     }

apps/api/src/lexicon/lexicons.ts

···
           },
         },
       },
+      songViewBasic: {
+        type: 'object',
+        properties: {
+          uri: {
+            type: 'string',
+            description: 'The URI of the song.',
+            format: 'at-uri',
+          },
+          title: {
+            type: 'string',
+            description: 'The title of the song.',
+          },
+          playCount: {
+            type: 'integer',
+            description: 'The number of times the song has been played.',
+            minimum: 0,
+          },
+        },
+      },
       listenerViewBasic: {
         type: 'object',
         properties: {
···
           },
           mostListenedSong: {
             type: 'ref',
-            ref: 'lex:app.rocksky.song.defs#songViewBasic',
+            ref: 'lex:app.rocksky.artist.defs#songViewBasic',
+          },
+          totalPlays: {
+            type: 'integer',
+            description: 'The total number of plays by the listener.',
+            minimum: 0,
+          },
+          rank: {
+            type: 'integer',
+            description:
+              'The rank of the listener among all listeners of the artist.',
+            minimum: 1,
           },
         },
       },

apps/api/src/lexicon/types/app/rocksky/artist/defs.ts

···
 import { lexicons } from '../../../../lexicons'
 import { isObj, hasProp } from '../../../../util'
 import { CID } from 'multiformats/cid'
-import type * as AppRockskySongDefs from '../song/defs'
 
 export interface ArtistViewBasic {
   /** The unique identifier of the artist. */
···
   return lexicons.validate('app.rocksky.artist.defs#artistViewDetailed', v)
 }
 
+export interface SongViewBasic {
+  /** The URI of the song. */
+  uri?: string
+  /** The title of the song. */
+  title?: string
+  /** The number of times the song has been played. */
+  playCount?: number
+  [k: string]: unknown
+}
+
+export function isSongViewBasic(v: unknown): v is SongViewBasic {
+  return (
+    isObj(v) &&
+    hasProp(v, '$type') &&
+    v.$type === 'app.rocksky.artist.defs#songViewBasic'
+  )
+}
+
+export function validateSongViewBasic(v: unknown): ValidationResult {
+  return lexicons.validate('app.rocksky.artist.defs#songViewBasic', v)
+}
+
 export interface ListenerViewBasic {
   /** The unique identifier of the actor. */
   id?: string
···
   displayName?: string
   /** The URL of the listener's avatar image. */
   avatar?: string
-  mostListenedSong?: AppRockskySongDefs.SongViewBasic
+  mostListenedSong?: SongViewBasic
+  /** The total number of plays by the listener. */
+  totalPlays?: number
+  /** The rank of the listener among all listeners of the artist. */
+  rank?: number
   [k: string]: unknown
 }
 

apps/api/src/xrpc/app/rocksky/artist/getArtistListeners.ts

···
+import type { Context } from "context";
+import { Effect, pipe } from "effect";
+import type { Server } from "lexicon";
+import type { ListenerViewBasic } from "lexicon/types/app/rocksky/artist/defs";
+import type { QueryParams } from "lexicon/types/app/rocksky/artist/getArtistListeners";
+
+export default function (server: Server, ctx: Context) {
+  const getArtistListeners = (params) =>
+    pipe(
+      { params, ctx },
+      retrieve,
+      Effect.flatMap(presentation),
+      Effect.retry({ times: 3 }),
+      Effect.timeout("10 seconds"),
+      Effect.catchAll((err) => {
+        console.error(err);
+        return Effect.succeed({ listeners: [] });
+      })
+    );
+  server.app.rocksky.artist.getArtistListeners({
+    handler: async ({ params }) => {
+      const result = await Effect.runPromise(getArtistListeners(params));
+      return {
+        encoding: "application/json",
+        body: result,
+      };
+    },
+  });
+}
+
+const retrieve = ({
+  params,
+  ctx,
+}: {
+  params: QueryParams;
+  ctx: Context;
+}): Effect.Effect<{ data: ArtistListener[] }, Error> => {
+  return Effect.tryPromise({
+    try: () =>
+      ctx.analytics.post("library.getArtistListeners", {
+        artist_id: params.uri,
+      }),
+    catch: (error) =>
+      new Error(`Failed to retrieve artist's listeners: ${error}`),
+  });
+};
+
+const presentation = ({
+  data,
+}: {
+  data: ArtistListener[];
+}): Effect.Effect<{ listeners: ListenerViewBasic[] }, never> => {
+  return Effect.sync(() => ({
+    listeners: data.map((item) => ({
+      id: item.user_id,
+      did: item.did,
+      handle: item.handle,
+      displayName: item.display_name,
+      avatar: item.avatar,
+      mostListenedSong: {
+        title: item.most_played_track,
+        uri: item.most_played_track_uri,
+        playCount: item.track_play_count,
+      },
+      totalPlays: item.total_artist_plays,
+      rank: item.listener_rank,
+    })),
+  }));
+};
+
+type ArtistListener = {
+  artist: string;
+  avatar: string;
+  did: string;
+  display_name: string;
+  handle: string;
+  listener_rank: number;
+  most_played_track: string;
+  most_played_track_uri: string;
+  total_artist_plays: number;
+  track_play_count: number;
+  user_id: string;
+};