psn-api Documentation

interface RarestThinTrophy {
  trophyId: number;        // Unique ID for this trophy (unique within the title)
  trophyHidden: boolean;   // True if this is a secret trophy
  earned: boolean;          // True if this trophy has been earned
  trophyType: "bronze" | "silver" | "gold" | "platinum"; // The trophy grade
  trophyRare: TrophyRarity; // Rarity of the trophy
  trophyEarnedRate: string; // Percentage of all users who have earned the trophy
}

interface Trophy {
  trophyId: number; // Unique ID for this trophy
  trophyHidden: boolean; // True if it is a secret trophy
  trophyType: "bronze" | "silver" | "gold" | "platinum"; // The trophy grade
  earned: boolean; // True if the trophy has been earned
  earnedDateTime: string; // ISO 8601 string (e.g., "2021-08-15T21:22:08Z"). Only returned if earned is true
  trophyDetail: string; // Description of the trophy
  trophyEarnedRate: string; // Percentage of all users who earned the trophy
  trophyGroupId: string; // "default" for standard set, or numeric (e.g., "001") for DLC
  trophyIconUrl: string; // URL for the trophy graphic
  trophyName: string; // Name of the trophy
  trophyProgressTargetValue: string; // Total required for unlock (PS5 titles only, if progress is tracked)
  trophyRare: TrophyRarity; // Rarity of the trophy
  trophyRewardImageUrl: string; // URL for reward graphic (PS5 titles only, if reward exists)
  trophyRewardName: string; // Name of the reward (PS5 titles only, if reward exists)
}

interface RecentlyPlayedGame {
  name: string; // The name of the game
  lastPlayedDateTime: string; // ISO date of last play (e.g., 2023-03-10T01:01:01.390000Z)
  conceptId: string; // ID used in store.playstation.com/en-is/concept/:conceptId
  titleId: string; // Product ID used in store.playstation.com/en-us/product/UP9000-$titleId-...
  platform: TitlePlatform | "UNKNOWN"; // Platform played on. "UNKNOWN" may appear if multiple users share a console
  entitlementId: string | null; // Used in store.playstation.com/en-ae/product/:entitlementId (primarily PS4)
  productId: string | null; // Product ID used in Store URLs (primarily PS4)
  image: {
    url: string; // URL to the game icon file
  };
}

interface TitleThinTrophy {
  trophyId: number;      // Unique ID for this trophy (unique within the title)
  trophyHidden: boolean; // True if it is a secret trophy
  trophyType: "bronze" | "silver" | "gold" | "platinum"; // The trophy grade
  trophyName: string;    // Name of the trophy
  trophyDetail: string;  // Description of the trophy
  trophyIconUrl: string; // URL for the trophy graphic
  trophyGroupId: string; // ID of the trophy group ("default" for standard set, "001", "002" etc. for DLC)
}

interface AccountDevice {
  deviceId: string;            // The unique device identifier
  deviceType: string;          // The device type/platform (e.g., PS5, PS4, PS3, PSVita)
  activationType: string;      // The activation type for the device (e.g., PRIMARY, PSN_GAME_V3)
  activationDate: string;      // The device activation date in ISO 8601 format (e.g., 2023-06-03T21:25:28.987Z)
  accountDeviceVector: string; // The account device vector (internal PlayStation identifier)
}

interface Title {
  titleId: string; // Example: "CUSA01433_00"
  name: string; // Example: "Rocket League®"
  localizedName: string;
  imageUrl: string;
  localizedImageUrl: string;
  category: "ps4_game" | "ps5_native_game" | "pspc_game" | "unknown";
  service: "none" | "none_purchased" | "ps_plus"; // Ownership type
  playCount: number;
  firstPlayedDateTime: string; // ISO 8601 format
  lastPlayedDateTime: string; // ISO 8601 format
  media: {
    screenshotUrl?: string;
    [key: string]: string | undefined;
  };
  concept: {
    id: number;
    titleIds: string[];
    name: string;
    media: {
      audios: any[];
      videos: any[];
      images: Array<{
        url: string;
        format: string;
        type: string;
      }>;
    };
  };
}

import { getTitleTrophies } from "psn-api";

// Example: Get all trophies for a PS3 game (Red Dead Redemption)
const ps3Response = await getTitleTrophies(authorization, "NPWR00867_00", "all", {
  npServiceName: "trophy"
});

// Example: Get all trophies for a PS5 game (Astro's Playroom)
const ps5Response = await getTitleTrophies(authorization, "NPWR20188_00", "all");

// Initial authentication
const authorization = await exchangeAccessCodeForAuthTokens(accessCode);

// Calculate and store expiration date
const now = new Date();
const expirationDate = new Date(
  now.getTime() + authorization.expiresIn * 1000
).toISOString();

// ... later, check if expired ...
const isAccessTokenExpired = new Date(expirationDate).getTime() < new Date().getTime();

if (isAccessTokenExpired) {
  // Use the refresh token to get a new access token
  const updatedAuthorization = await exchangeRefreshTokenForAuthTokens(
    authorization.refreshToken
  );
  
  // Store the new accessToken and update the expirationDate using updatedAuthorization.expiresIn
}

// Example: Retrieve a list of games the user has earned trophies for
const trophyTitlesResponse = await getUserTitles(
  { accessToken: authorization.accessToken },
  "me"
);

import { exchangeNpssoForAccessCode } from "psn-api";

const accessCode = await exchangeNpssoForAccessCode("<my 64-digit NPSSO>");
console.log(accessCode); // Example output: "v3.ABCDEF"