@rocksky/sdk 0.7.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocksky/sdk",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "TypeScript SDK for Rocksky — built on atcute: AppView reads, AT Protocol PDS writes (scrobble, like, follow, shout), a local dedup index, and Jetstream real-time sync.",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir ./dist --target node --format esm --external none && bun run build:types",
+    "build": "bun build ./src/index.ts --outdir ./dist --target node --format esm --packages external && bun run build:types",
     "build:types": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "bun test",

package/src/agent.ts

@@ -16,6 +16,7 @@ import type {
   ArtistRecord,
   ActorTrackView,
   ScrobbleRecord,
+  ShoutGif,
   SongRecord,
 } from "./generated/types.js";
 import type { IndexStats, RockskyIndex } from "./dedup.js";
@@ -303,23 +304,33 @@ export class Agent {
     return this.create(C_FOLLOW, { subject: did, createdAt: nowISO() });
   }
 
-  /** Post a shout on a subject. Returns the shout URI. */
-  shout(subjectUri: string, subjectCid: string, message: string): Promise<string> {
-    return this.create(C_SHOUT, { subject: { uri: subjectUri, cid: subjectCid }, message, createdAt: nowISO() });
+  /** Post a shout on a subject. Returns the shout URI. Pass at least one of
+   * `message` / `gif` — `message` may be omitted when a GIF/sticker/clip is
+   * attached. */
+  shout(subjectUri: string, subjectCid: string, message?: string, gif?: ShoutGif): Promise<string> {
+    return this.create(C_SHOUT, {
+      subject: { uri: subjectUri, cid: subjectCid },
+      ...(message !== undefined ? { message } : {}),
+      ...(gif ? { gif } : {}),
+      createdAt: nowISO(),
+    });
   }
 
-  /** Reply to a shout, with a parent strong-ref. */
+  /** Reply to a shout, with a parent strong-ref. Pass at least one of `message`
+   * / `gif` — `message` may be omitted when a GIF/sticker/clip is attached. */
   replyShout(
     subjectUri: string,
     subjectCid: string,
     parentUri: string,
     parentCid: string,
-    message: string,
+    message?: string,
+    gif?: ShoutGif,
   ): Promise<string> {
     return this.create(C_SHOUT, {
       subject: { uri: subjectUri, cid: subjectCid },
       parent: { uri: parentUri, cid: parentCid },
-      message,
+      ...(message !== undefined ? { message } : {}),
+      ...(gif ? { gif } : {}),
       createdAt: nowISO(),
     });
   }

package/src/client.ts

@@ -6,14 +6,48 @@ import type {
   ActorProfileViewBasic,
   ActorProfileViewDetailed,
   AlbumViewBasic,
+  AlbumViewDetailed,
   ArtistViewBasic,
+  ArtistViewDetailed,
+  ChartsView,
+  FeedGeneratorsView,
+  FeedRecommendationsView,
+  FeedRecommendedAlbumsView,
+  FeedRecommendedArtistsView,
   FeedSearchResultsView,
+  FeedStoriesView,
+  FeedView,
   GetActorAlbumsOutput,
   GetActorArtistsOutput,
+  GetActorCompatibilityOutput,
+  GetActorNeighboursOutput,
+  GetActorPlaylistsOutput,
   GetActorScrobblesOutput,
+  GetAlbumShoutsOutput,
+  GetApikeysOutput,
+  GetArtistListenersOutput,
+  GetArtistRecentListenersOutput,
+  GetArtistShoutsOutput,
+  GetFeedGeneratorOutput,
+  GetMirrorSourcesOutput,
+  GetProfileShoutsOutput,
+  GetShoutRepliesOutput,
+  GetSongRecentListenersOutput,
+  GetTrackShoutsOutput,
+  GetUnreadCountOutput,
+  ListNotificationsOutput,
+  PlayerCurrentlyPlayingViewDetailed,
+  PlayerPlaybackQueueViewDetailed,
+  PlaylistGetPlaylistsOutput,
+  PlaylistViewDetailed,
+  RockboxSettingsView,
   ScrobbleViewBasic,
   SongViewBasic,
+  SongViewDetailed,
   StatsGlobalStatsView,
+  StatsView,
+  StatsWrappedView,
+  UpdateSeenOutput,
 } from "./generated/types.js";
 
 /**
@@ -303,51 +337,60 @@ export class RockskyClient {
     return this.query("app.rocksky.stats.getGlobalStats", {});
   }
 
-  // ---- raw-JSON long tail: bespoke shapes returned as `unknown` ----------
+  // ---- detail reads (typed against the generated lexicon views) ----------
 
   /** A feed by its at:// URI (paginate via `cursor`). */
-  feed(feed: string, limit = 50, cursor?: string): Promise<unknown> {
+  feed(feed: string, limit = 50, cursor?: string): Promise<FeedView> {
     return this.query("app.rocksky.feed.getFeed", { feed, limit, cursor });
   }
   /** A single album with its tracklist. */
-  album(uri: string): Promise<unknown> {
+  album(uri: string): Promise<AlbumViewDetailed> {
     return this.query("app.rocksky.album.getAlbum", { uri });
   }
   /** A single artist with detail. */
-  artist(uri: string): Promise<unknown> {
+  artist(uri: string): Promise<ArtistViewDetailed> {
     return this.query("app.rocksky.artist.getArtist", { uri });
   }
   /** Resolve full canonical metadata for a bare title + artist
    * (`app.rocksky.song.matchSong`); optionally anchor with `mbId` / `isrc`. */
-  matchSong(title: string, artist: string, mbId?: string, isrc?: string): Promise<unknown> {
+  matchSong(title: string, artist: string, mbId?: string, isrc?: string): Promise<SongViewDetailed> {
     return this.query("app.rocksky.song.matchSong", { title, artist, mbId, isrc });
   }
   /** A single song by at:// `uri` (or by `mbid` / `isrc` / `spotifyId`). */
-  song(opts: { uri?: string; mbid?: string; isrc?: string; spotifyId?: string }): Promise<unknown> {
+  song(opts: {
+    uri?: string;
+    mbid?: string;
+    isrc?: string;
+    spotifyId?: string;
+  }): Promise<SongViewDetailed> {
     return this.query("app.rocksky.song.getSong", opts);
   }
   /** An actor's playlists. */
-  actorPlaylists(actor: string, limit = 50, offset = 0): Promise<unknown> {
+  actorPlaylists(actor: string, limit = 50, offset = 0): Promise<GetActorPlaylistsOutput> {
     return this.query("app.rocksky.actor.getActorPlaylists", { did: actor, limit, offset });
   }
   /** Actors with similar taste to `actor`. */
-  neighbours(actor: string): Promise<unknown> {
+  neighbours(actor: string): Promise<GetActorNeighboursOutput> {
     return this.query("app.rocksky.actor.getActorNeighbours", { did: actor });
   }
   /** Music compatibility between the viewer and `actor` (auth). */
-  compatibility(actor: string): Promise<unknown> {
+  compatibility(actor: string): Promise<GetActorCompatibilityOutput> {
     return this.query("app.rocksky.actor.getActorCompatibility", { did: actor });
   }
   /** An artist's all-time listeners. */
-  artistListeners(uri: string, limit = 50, offset = 0): Promise<unknown> {
+  artistListeners(uri: string, limit = 50, offset = 0): Promise<GetArtistListenersOutput> {
     return this.query("app.rocksky.artist.getArtistListeners", { uri, limit, offset });
   }
   /** An artist's recent listeners. */
-  artistRecentListeners(uri: string, limit = 50, offset = 0): Promise<unknown> {
+  artistRecentListeners(
+    uri: string,
+    limit = 50,
+    offset = 0,
+  ): Promise<GetArtistRecentListenersOutput> {
     return this.query("app.rocksky.artist.getArtistRecentListeners", { uri, limit, offset });
   }
   /** A song's recent listeners. */
-  songRecentListeners(uri: string, limit = 50, offset = 0): Promise<unknown> {
+  songRecentListeners(uri: string, limit = 50, offset = 0): Promise<GetSongRecentListenersOutput> {
     return this.query("app.rocksky.song.getSongRecentListeners", { uri, limit, offset });
   }
   /** A scrobble time-series chart. Scope with any of `did` / `artisturi` /
@@ -360,91 +403,113 @@ export class RockskyClient {
     genre?: string;
     from?: string;
     to?: string;
-  }): Promise<unknown> {
+  }): Promise<ChartsView> {
     return this.query("app.rocksky.charts.getScrobblesChart", opts);
   }
   /** List the available feed generators. */
-  feedGenerators(size?: number): Promise<unknown> {
+  feedGenerators(size?: number): Promise<FeedGeneratorsView> {
     return this.query("app.rocksky.feed.getFeedGenerators", { size });
   }
   /** A single feed generator's record. */
-  feedGenerator(feed: string): Promise<unknown> {
+  feedGenerator(feed: string): Promise<GetFeedGeneratorOutput> {
     return this.query("app.rocksky.feed.getFeedGenerator", { feed });
   }
   /** The stories row. */
-  stories(size?: number, feed?: string, following?: boolean): Promise<unknown> {
+  stories(size?: number, feed?: string, following?: boolean): Promise<FeedStoriesView> {
     return this.query("app.rocksky.feed.getStories", { size, feed, following });
   }
   /** Track recommendations for `actor`. */
-  recommendations(actor: string, limit?: number): Promise<unknown> {
+  recommendations(actor: string, limit?: number): Promise<FeedRecommendationsView> {
     return this.query("app.rocksky.feed.getRecommendations", { did: actor, limit });
   }
   /** Artist recommendations for `actor`. */
-  artistRecommendations(actor: string, limit?: number): Promise<unknown> {
+  artistRecommendations(actor: string, limit?: number): Promise<FeedRecommendedArtistsView> {
     return this.query("app.rocksky.feed.getArtistRecommendations", { did: actor, limit });
   }
   /** Album recommendations for `actor`. */
-  albumRecommendations(actor: string, limit?: number): Promise<unknown> {
+  albumRecommendations(actor: string, limit?: number): Promise<FeedRecommendedAlbumsView> {
     return this.query("app.rocksky.feed.getAlbumRecommendations", { did: actor, limit });
   }
   /** An actor's aggregate stats. */
-  stats(actor: string): Promise<unknown> {
+  stats(actor: string): Promise<StatsView> {
     return this.query("app.rocksky.stats.getStats", { did: actor });
   }
   /** An actor's year-in-review. */
-  wrapped(actor: string, year?: number): Promise<unknown> {
+  wrapped(actor: string, year?: number): Promise<StatsWrappedView> {
     return this.query("app.rocksky.stats.getWrapped", { did: actor, year });
   }
   /** The viewer's configured scrobble mirror sources (auth). */
-  mirrorSources(): Promise<unknown> {
+  mirrorSources(): Promise<GetMirrorSourcesOutput> {
     return this.query("app.rocksky.mirror.getMirrorSources", {});
   }
   /** What `actor` is playing now. */
-  currentlyPlaying(playerId?: string, actor?: string): Promise<unknown> {
+  currentlyPlaying(playerId?: string, actor?: string): Promise<PlayerCurrentlyPlayingViewDetailed> {
     return this.query("app.rocksky.player.getCurrentlyPlaying", { playerId, actor });
   }
   /** A player's playback queue. */
-  playbackQueue(playerId: string): Promise<unknown> {
+  playbackQueue(playerId: string): Promise<PlayerPlaybackQueueViewDetailed> {
     return this.query("app.rocksky.player.getPlaybackQueue", { playerId });
   }
   /** What `actor` is playing now on Spotify. */
-  spotifyCurrentlyPlaying(actor: string): Promise<unknown> {
+  spotifyCurrentlyPlaying(actor: string): Promise<PlayerCurrentlyPlayingViewDetailed> {
     return this.query("app.rocksky.spotify.getCurrentlyPlaying", { actor });
   }
   /** The playlist catalog. */
-  playlists(limit = 50, offset = 0): Promise<unknown> {
+  playlists(limit = 50, offset = 0): Promise<PlaylistGetPlaylistsOutput> {
     return this.query("app.rocksky.playlist.getPlaylists", { limit, offset });
   }
   /** A single playlist with its items. */
-  playlist(uri: string): Promise<unknown> {
+  playlist(uri: string): Promise<PlaylistViewDetailed> {
     return this.query("app.rocksky.playlist.getPlaylist", { uri });
   }
   /** Shouts on an album. */
-  albumShouts(uri: string, limit = 50, offset = 0): Promise<unknown> {
+  albumShouts(uri: string, limit = 50, offset = 0): Promise<GetAlbumShoutsOutput> {
     return this.query("app.rocksky.shout.getAlbumShouts", { uri, limit, offset });
   }
   /** Shouts on an artist. */
-  artistShouts(uri: string, limit = 50, offset = 0): Promise<unknown> {
+  artistShouts(uri: string, limit = 50, offset = 0): Promise<GetArtistShoutsOutput> {
     return this.query("app.rocksky.shout.getArtistShouts", { uri, limit, offset });
   }
   /** Shouts on a profile. */
-  profileShouts(actor: string, limit = 50, offset = 0): Promise<unknown> {
+  profileShouts(actor: string, limit = 50, offset = 0): Promise<GetProfileShoutsOutput> {
     return this.query("app.rocksky.shout.getProfileShouts", { did: actor, limit, offset });
   }
   /** Shouts on a track. */
-  trackShouts(uri: string): Promise<unknown> {
+  trackShouts(uri: string): Promise<GetTrackShoutsOutput> {
     return this.query("app.rocksky.shout.getTrackShouts", { uri });
   }
   /** Replies to a shout. */
-  shoutReplies(uri: string, limit = 50, offset = 0): Promise<unknown> {
+  shoutReplies(uri: string, limit = 50, offset = 0): Promise<GetShoutRepliesOutput> {
     return this.query("app.rocksky.shout.getShoutReplies", { uri, limit, offset });
   }
   /** An actor's Rockbox EQ / audio settings. */
-  audioSettings(actor: string): Promise<unknown> {
+  audioSettings(actor: string): Promise<RockboxSettingsView> {
     return this.query("app.rocksky.rockbox.getAudioSettings", { did: actor });
   }
   /** The viewer's API keys (auth). */
-  apikeys(limit = 50, offset = 0): Promise<unknown> {
+  apikeys(limit = 50, offset = 0): Promise<GetApikeysOutput> {
     return this.query("app.rocksky.apikey.getApikeys", { limit, offset });
   }
+
+  // ---- notifications (auth-gated — construct the client with a token) -----
+
+  /** The authenticated viewer's unread-notification count. */
+  unreadCount(): Promise<GetUnreadCountOutput> {
+    return this.query("app.rocksky.notification.getUnreadCount", {});
+  }
+  /** The authenticated viewer's notifications, most recent first. `limit`
+   * defaults to 30 server-side; paginate via `cursor`. */
+  notifications(limit = 30, cursor?: string): Promise<ListNotificationsOutput> {
+    return this.query("app.rocksky.notification.listNotifications", { limit, cursor });
+  }
+  /** Mark notifications as viewed. Pass the notification `ids` to mark, or omit
+   * to mark **all** of the viewer's notifications. Returns the number remaining
+   * unread. */
+  async updateSeen(ids?: string[]): Promise<UpdateSeenOutput> {
+    const res = await this.rpc.post("app.rocksky.notification.updateSeen" as never, {
+      input: (ids && ids.length ? { ids } : {}) as never,
+    } as never);
+    if (!res.ok) throw new RockskyError(res.data);
+    return res.data as UpdateSeenOutput;
+  }
 }

package/src/generated/types.ts

@@ -103,6 +103,8 @@ export interface ActorTrackView {
   source?: string;
   /** MusicBrainz recording ID, if available. */
   recordingMbId?: string;
+  /** The track's position within its album, if known (>= 1). */
+  trackNumber?: number;
 }
 
 export interface AddDirectoryToQueueParams {
@@ -492,10 +494,6 @@ export interface DescribeFeedGeneratorOutput {
   feeds?: FeedUriView[];
 }
 
-export interface DescribeFeedGeneratorParams {
-
-}
-
 export interface DislikeShoutInput {
   /** The unique identifier of the shout to dislike */
   uri?: AtUri;
@@ -1407,6 +1405,11 @@ export interface GetTrackShoutsParams {
   uri: AtUri;
 }
 
+export interface GetUnreadCountOutput {
+  /** The number of unread notifications. */
+  count: number;
+}
+
 export interface GetUserOutput {
 
 }
@@ -1570,6 +1573,19 @@ export interface LikeSongInput {
   uri?: AtUri;
 }
 
+export interface ListNotificationsOutput {
+  notifications: NotificationView[];
+  /** The number of unread notifications. */
+  unreadCount: number;
+  /** A cursor value to pass to subsequent calls to get the next page of results. */
+  cursor?: string;
+}
+
+export interface ListNotificationsParams {
+  limit?: number;
+  cursor?: string;
+}
+
 export interface MatchSongParams {
   /** The title of the song to retrieve */
   title: string;
@@ -1596,6 +1612,38 @@ export interface MirrorSourceView {
   lastScrobbleSeenAt?: DateTime;
 }
 
+/** The user who triggered a notification. */
+export interface NotificationActor {
+  /** The unique identifier of the actor. */
+  id?: string;
+  /** The decentralized identifier of the actor. */
+  did?: Did;
+  /** The handle of the actor. */
+  handle?: AtIdentifier;
+  /** The display name of the actor. */
+  displayName?: string;
+  /** The URL of the actor's avatar image. */
+  avatar?: Uri;
+}
+
+export interface NotificationView {
+  /** The unique identifier of the notification. */
+  id: string;
+  /** The notification type: like_scrobble, follow, comment_scrobble, comment_profile, reply, or react_comment. */
+  type: string;
+  /** Whether the notification has been viewed. */
+  read: boolean;
+  /** When the notification was created. */
+  createdAt: DateTime;
+  /** The at-uri of the subject the notification relates to. */
+  subjectUri?: string;
+  /** The id of the related shout, if any. */
+  shoutId?: string;
+  /** The content of the related shout, if any. */
+  shoutContent?: string;
+  actor?: NotificationActor;
+}
+
 export interface PingOutput {
 
 }
@@ -2135,13 +2183,41 @@ export interface ShoutAuthor {
   avatar?: Uri;
 }
 
+/** A GIF, sticker, or clip embedded in a shout. `url` may point at an image (GIF/WebP) or a video (MP4); the client decides how to render it from the file extension. */
+export interface ShoutGif {
+  /** Direct URL of the animated GIF/MP4. */
+  url: Uri;
+  /** Smaller still/preview image URL. */
+  previewUrl?: Uri;
+  /** Alternative text describing the media. */
+  alt?: string;
+  /** The intrinsic width of the media in pixels. */
+  width?: number;
+  /** The intrinsic height of the media in pixels. */
+  height?: number;
+}
+
+/** A mention of another actor within the shout message, anchored to a UTF-8 byte range in the message. */
+export interface ShoutMention {
+  /** The DID of the mentioned actor. */
+  did: Did;
+  /** Inclusive UTF-8 byte offset of the mention start. */
+  byteStart: number;
+  /** Exclusive UTF-8 byte offset of the mention end. */
+  byteEnd: number;
+}
+
 export interface ShoutRecord {
-  /** The message of the shout. */
-  message: string;
+  /** The message of the shout. Optional when a gif/sticker/clip is attached. */
+  message?: string;
   /** The date when the shout was created. */
   createdAt: DateTime;
   parent?: StrongRef;
   subject: StrongRef;
+  /** An attached GIF, sticker, or clip (e.g. from KLIPY). */
+  gif?: ShoutGif;
+  /** Mentions of other actors within the message, anchored to UTF-8 byte ranges. */
+  facets?: ShoutMention[];
 }
 
 export interface ShoutView {
@@ -2155,6 +2231,10 @@ export interface ShoutView {
   createdAt?: DateTime;
   /** The author of the shout. */
   author?: ShoutAuthor;
+  /** An attached GIF, sticker, or clip. */
+  gif?: ShoutGif;
+  /** Mentions of other actors within the message, anchored to UTF-8 byte ranges. */
+  facets?: ShoutMention[];
 }
 
 export interface SongFirstScrobbleView {
@@ -2177,6 +2257,34 @@ export interface SongGetSongParams {
   spotifyId?: string;
 }
 
+/** A ranked candidate match for a song from an external metadata provider. */
+export interface SongMatchView {
+  /** The provider's numeric identifier for the matched track. */
+  id?: number;
+  /** The title of the matched track. */
+  title?: string;
+  /** The artist of the matched track. */
+  artist?: string;
+  /** The album of the matched track. */
+  album?: string;
+  /** The URL of the matched track's album art image. */
+  albumArt?: Uri;
+  /** The International Standard Recording Code (ISRC) of the matched track. */
+  isrc?: string;
+  /** The duration of the matched track in milliseconds. */
+  durationMs?: number;
+  /** A URL to the matched track on the provider. */
+  link?: Uri;
+  /** A URL to a short audio preview of the matched track. */
+  preview?: Uri;
+  /** The provider's popularity rank for the matched track. */
+  rank?: number;
+  /** Whether the matched track has explicit lyrics. */
+  explicit?: boolean;
+  /** Match confidence score in the range 0-100 (higher is better). */
+  score?: number;
+}
+
 export interface SongRecentListenerView {
   /** The unique identifier of the listener. */
   id?: string;
@@ -2330,6 +2438,8 @@ export interface SongViewDetailed {
   artists?: ArtistViewBasic[];
   /** The first scrobble of this song on Rocksky. */
   firstScrobble?: SongFirstScrobbleView;
+  /** Ranked list of candidate matches from external metadata providers (e.g. Deezer). Additive field returned by matchSong; may be empty. */
+  matches?: SongMatchView[];
 }
 
 export interface SpotifyGetCurrentlyPlayingParams {
@@ -2596,6 +2706,16 @@ export interface UpdatePlaylistOutput {
 
 }
 
+export interface UpdateSeenInput {
+  /** The ids of the notifications to mark as viewed. Omit to mark all. */
+  ids?: string[];
+}
+
+export interface UpdateSeenOutput {
+  /** The number of unread notifications remaining. */
+  unreadCount: number;
+}
+
 /**
  * Map of every XRPC method (NSID) to the type of its response body.
  * Endpoints with no output map to `void`. Used by the SDK to type method
@@ -2697,6 +2817,9 @@ export interface Endpoints {
   "app.rocksky.like.likeSong": SongViewDetailed;
   "app.rocksky.mirror.getMirrorSources": GetMirrorSourcesOutput;
   "app.rocksky.mirror.putMirrorSource": MirrorSourceView;
+  "app.rocksky.notification.getUnreadCount": GetUnreadCountOutput;
+  "app.rocksky.notification.listNotifications": ListNotificationsOutput;
+  "app.rocksky.notification.updateSeen": UpdateSeenOutput;
   "app.rocksky.player.addDirectoryToQueue": void;
   "app.rocksky.player.addItemsToQueue": void;
   "app.rocksky.player.getCurrentlyPlaying": PlayerCurrentlyPlayingViewDetailed;