feat: add docs site and improve types (#19)

* docs: run setup command

* docs: start working on docusaurus website

* docs: start working on docusaurus website

* feat(docs): add more docusaurus pages

* docs: finish up on docusaurus

* docs: switch to nextra

* chore: update docs

README.md

@@ -1,18 +1,18 @@
 <p align="center">
-  <img width="40%" height="40%" src="psx.png">
+  <img width="40%" height="40%" src="psx.png" />
 </p>
 
 # PSN API
 
-> A low-level API for getting data from the PlayStation Network.
+> A low-level API for getting trophy data from the PlayStation Network.
 
 <p align="center">
   <a href="https://github.com/prettier/prettier">
-    <img src="https://img.shields.io/badge/styled_with-prettier-ff69b4.svg?style=flat-square" alt="Styled with Prettier">
+    <img src="https://img.shields.io/badge/styled_with-prettier-ff69b4.svg?style=flat-square" alt="Styled with Prettier" />
   </a>
 
   <a href="https://github.com/semantic-release/semantic-release">
-    <img src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg" alt="Semantic Release">
+    <img src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg" alt="Semantic Release" />
   </a>
 
   <a href="https://codeclimate.com/github/achievements-app/psn-api/maintainability">

src/models/access-token-response.model.ts

@@ -1,9 +1,18 @@
 export interface AccessTokenResponse {
+  /** Used to retrieve data from the PSN API. */
   accessToken: string;
+
+  /** When the access token will expire. */
   expiresIn: number;
+
   idToken: string;
+
+  /** Used to retrieve a new access token. */
   refreshToken: string;
+
+  /** When the refresh token will expire. */
   refreshTokenExpiresIn: number;
+
   scope: string;
   tokenType: string;
 }

src/models/all-call-options.model.ts

@@ -10,10 +10,10 @@ export interface AllCallOptions {
    */
   npServiceName: "trophy" | "trophy2";
 
-  /** Limit the number of titles returned. */
+  /** Limit the number of entities returned. */
   limit: number;
 
-  /** Return title data from this result onwards. */
+  /** Return entity data from this result onwards. */
   offset: number;
 
   /*

src/models/index.ts

@@ -2,15 +2,19 @@ export * from "./access-token-response.model";
 export * from "./all-call-options.model";
 export * from "./authorization-payload.model";
 export * from "./call-valid-headers.model";
+export * from "./rarest-thin-trophy.model";
 export * from "./title-platform.model";
+export * from "./title-thin-trophy.model";
 export * from "./title-trophies-response.model";
 export * from "./title-trophy-groups-response.model";
 export * from "./trophy.model";
 export * from "./trophy-counts.model";
+export * from "./trophy-group-earnings.model";
 export * from "./trophy-rarity.model";
 export * from "./trophy-title.model";
 export * from "./trophy-title.model";
 export * from "./user-summarized-trophies-by-trophy-group-response.model";
+export * from "./user-thin-trophy.model";
 export * from "./user-titles-response.model";
 export * from "./user-trophies-earned-for-title-response.model";
 export * from "./user-trophy-profile-summary-response.model";

src/models/rarest-thin-trophy.model.ts

@@ -0,0 +1,11 @@
+import type { Trophy } from "./trophy.model";
+
+export type RarestThinTrophy = Pick<
+  Trophy,
+  | "trophyId"
+  | "trophyHidden"
+  | "earned"
+  | "trophyType"
+  | "trophyRare"
+  | "trophyEarnedRate"
+>;

src/models/title-thin-trophy.model.ts

@@ -0,0 +1,12 @@
+import type { Trophy } from "./trophy.model";
+
+export type TitleThinTrophy = Pick<
+  Trophy,
+  | "trophyId"
+  | "trophyHidden"
+  | "trophyType"
+  | "trophyName"
+  | "trophyDetail"
+  | "trophyIconUrl"
+  | "trophyGroupId"
+>;

src/models/title-trophies-response.model.ts

@@ -1,14 +1,14 @@
-import type { Trophy } from "./trophy.model";
+import type { TitleThinTrophy } from "./title-thin-trophy.model";
 
 export interface TitleTrophiesResponse {
-  /** The current version of the trophy set. Some trophy sets receive updates. */
+  /** The current version of the trophy set. Some trophy sets receive updates from the developer. */
   trophySetVersion: string;
 
-  /** `true` if this title has additional trophy groups. */
+  /** `true` if this title has additional trophy groups. This is commonly used for DLC, but some games add additional trophies as separate groups post-release (such as Astro's Playroom and Horizon Zero Dawn). */
   hasTrophyGroups: boolean;
 
   /** Individual object for each trophy. */
-  trophies: Trophy[];
+  trophies: TitleThinTrophy[];
 
   /** Total trophies in the group (or total trophies for the title if `"all"` specified) */
   totalItemCount: number;

src/models/title-trophy-groups-response.model.ts

@@ -2,7 +2,7 @@ import type { TrophyCounts } from "./trophy-counts.model";
 import type { TrophyGroup } from "./trophy-group.model";
 
 export interface TitleTrophyGroupsResponse {
-  /** The current version of the trophy set. Some trophy sets receive updates. */
+  /** The current version of the trophy set. Some trophy sets receive updates from the developer. */
   trophySetVersion: string;
 
   /** The title name that this trophy belongs to. */
@@ -13,20 +13,20 @@ export interface TitleTrophyGroupsResponse {
 
   /**
    * The platform this title belongs to. Some games have trophy sets which
-   * are shared between multiple platforms (ie. PS4,PSVITA).
-   * The platforms in these instances will be comma separated.
+   * are shared between multiple platforms (eg. PS4,PSVITA).
+   * The platforms in these instances will be comma-separated.
    */
   trophyTitlePlatform: string;
 
   /** Total number of trophies for the title by type. */
   definedTrophies: TrophyCounts;
 
-  /** Individual object for each trophy group returned. */
+  /** Individual entities for each trophy group associated with the given title. */
   trophyGroups: TrophyGroup[];
 
   /**
    * The title description that this trophy belongs to.
-   * This applies to PS3, PS4, and PS Vita titles only.
+   * This is a legacy property that applies to PS3, PS4, and PS Vita titles only.
    */
   trophyTitleDetail?: string;
 }

src/models/trophy-counts.model.ts

@@ -1,13 +1,13 @@
 export interface TrophyCounts {
-  /** Total bronze trophies from all trophy groups. */
+  /** Total count of bronze trophies. */
   bronze: number;
 
-  /** Total silver trophies from all trophy groups. */
+  /** Total count of silver trophies. */
   silver: number;
 
-  /** Total gold trophies from all trophy groups. */
+  /** Total count of gold trophies. */
   gold: number;
 
-  /** Total platinum trophies from all trophy groups. */
-  platinum: number;
+  /** 1 if the group contains a platinum trophy. */
+  platinum: 0 | 1;
 }

src/models/trophy-group-earnings.model.ts

@@ -0,0 +1,24 @@
+import type { TrophyCounts } from "./trophy-counts.model";
+import type { TrophyGroup } from "./trophy-group.model";
+
+type FromTrophyGroup = Pick<TrophyGroup, "trophyGroupId">;
+
+export interface TrophyGroupEarnings extends FromTrophyGroup {
+  /**
+   * The percentage completion of the trophy group by the user.
+   * @example `100`
+   * @example `20`
+   */
+  progress: number;
+
+  /** The account's number of earned trophies for the trophy group by grade. */
+  earnedTrophies: TrophyCounts;
+
+  /**
+   * An ISO 8601 string representing the date the
+   * group progress was updated (such as when a
+   * trophy was earned).
+   * @example `"2021-08-15T21:22:08Z"`
+   */
+  lastUpdatedDateTime: string;
+}

src/models/trophy-group.model.ts

@@ -2,22 +2,28 @@ import type { TrophyCounts } from "./trophy-counts.model";
 
 export interface TrophyGroup {
   /**
-   * ID of the trophy group this trophy belongs to.
+   * ID of the trophy group.
    *
    * A game's standard set of trophies will have a value of `"default"`,
-   * whereas DLC increments in values such as `"001"` and `"002"`.
+   * whereas additional groups (such as those added from DLC) will
+   * increment in values such as `"001"` and `"002"`.
+   * @example "default"
+   * @example "001"
    */
   trophyGroupId: string;
 
-  /** Name of the trophy group. */
+  /**
+   * Name of the trophy group.
+   * @example "ASTRO's PLAYROOM"
+   */
   trophyGroupName: string;
 
   /** URL of the icon for the trophy group. */
   trophyGroupIconUrl: string;
 
-  /** Number of trophies for the trophy group by type. */
+  /** Number of trophies for the trophy group by grade. */
   definedTrophies: TrophyCounts;
 
-  /** Description of the trophy group. This applies to PS3, PS4, and PS Vita titles only. */
+  /** Description of the trophy group. This is a legacy property, only applying to PS3, PS4, and PS Vita titles. */
   trophyGroupDetail?: string;
 }

src/models/trophy-title.model.ts

@@ -6,7 +6,7 @@ export interface TrophyTitle {
    * `"trophy"` for PS3, PS4, or PS Vita platforms.
    * `"trophy2"` for the PS5 platform.
    */
-  npServiceName: string;
+  npServiceName: "trophy" | "trophy2";
 
   /**
    * Unique ID of the title. This is later required for requesting detailed
@@ -17,6 +17,7 @@ export interface TrophyTitle {
   /** The current version of the trophy set. Some trophy sets receive updates. */
   trophySetVersion: string;
 
+  /** The game name. */
   trophyTitleName: string;
 
   /** URL of the icon for the given title. */
@@ -25,35 +26,46 @@ export interface TrophyTitle {
   /**
    * The platform this title belongs to. Some games have trophy sets which are
    * shared between multiple platforms (ie. PS4,PSVITA). The platforms will be
-   * comma separated.
+   * comma-separated.
    */
   trophyTitlePlatform: TitlePlatform | string;
 
   /**
-   * True if the title has multiple groups of trophies
-   * (eg. DLC trophies which are separate from the main trophy list)
+   * `true` if the title has multiple groups of trophies beyond the `"default"` group.
    */
   hasTrophyGroups: boolean;
 
-  /** Number of trophies for the title by type */
+  /** Number of trophies for the title by type. */
   definedTrophies: TrophyCounts;
 
-  /** Percentage of trophies earned for the title */
+  /**
+   * Percentage of trophies earned for the title by the user.
+   * @example 100
+   * @example 25
+   */
   progress: number;
 
-  /** Number of trophies for the title which have been earned by type */
+  /** Number of trophies for the title which have been earned by grade. */
   earnedTrophies: TrophyCounts;
 
   /**
-   * Title has been hidden on the accounts trophy list.
+   * `true` if the title has been hidden on the account's trophy list.
    * This applies to the authenticating account only.
    * The title will not be returned if it has been hidden on another account.
    */
   hiddenFlag: boolean;
 
-  /** Date most recent trophy earned for the title. */
+  /**
+   * An ISO 8601 string representing the date the most
+   * recent trophy was earned for the title.
+   * @example `"2021-08-15T21:22:08Z"`
+   */
   lastUpdatedDateTime: string;
 
-  /** The title description. This applies to PS3, PS4, and PS Vita titles only. */
+  /**
+   * The title description.
+   * This is a legacy property that applies to
+   * PS3, PS4, and PS Vita titles only.
+   */
   trophyTitleDetail?: string;
 }

src/models/trophy.model.ts

@@ -14,7 +14,11 @@ export interface Trophy {
   /** `true` if this trophy has been earned. */
   earned?: boolean;
 
-  /** Date trophy was earned. Only returned if `earned` is `true`. */
+  /**
+   * An ISO 8601 string representing the date the
+   * trophy was earned. Only truthy if `earned` is `true`.
+   * @example `"2021-08-15T21:22:08Z"`
+   */
   earnedDateTime?: string;
 
   /** Description of the trophy. */