psn-api

A low-level API for getting trophy data from the PlayStation Network.

psn-api is a reference implementation of a community effort to document Sony's APIs for PlayStation authorization and trophy metadata. It saves you the hassle of implementing this community reference yourself by offering a strongly-typed, well-tested, and lightweight package.

Features

✅  Modular by design, and supports tree-shaking.
✅  Aligns with the community API documentation.
✅  Supports Node environments (14 and above).
✅  Supports browsers.
✅  Ships with TypeScript support and types.
✅  Tiny, <2Kb.

Docs site

The docs site for the library can be found at https://psn-api.achievements.app.

Getting started

Install

npm install --save psn-api

OR

yarn add psn-api

Usage with Node

Node 14 and above are officially supported. The package can be imported via:

const psn = require("psn-api");

Usage with TypeScript

You can use import syntax to utilize the package in your app. This library provides its own type definitions. "It just works", no need to install anything from @types.

import { getUserTrophiesEarnedForTitle } from "psn-api";

Understanding the Promise-based API

All methods in the API are async and return a native Promise.

These methods can be used with the native Promise API or the more modern async/await syntax.

// Native Promise API.
exchangeCodeForAccessToken("myCode").then((authTokensResponse) => {
  console.log({ authTokensResponse });
});

// async/await syntax.
const authTokensResponse = await exchangeCodeForAccessToken("myCode");
console.log({ authTokensResponse });

How to obtain an authentication token

To use any endpoint function in the API, you must first be authorized by PSN. Fortunately, this is a fairly straightforward process.

1. In your web browser, visit https://www.playstation.com/, click the "Sign In" button, and log in with a PSN account.

2. In the same browser (due to a persisted cookie), visit https://ca.account.sony.com/api/v1/ssocookie. You will see a JSON response that looks something like:

{"npsso":"<64 character token>"}

Copy your NPSSO. Do not expose it anywhere publicly, it is equivalent to your password.

3. You can now obtain an authentication token using your NPSSO with the following function calls from this package.

// This is the value you copied from the previous step.
const myNpsso = "<64 character token>";

// We'll exchange your NPSSO for a special access code.
const accessCode = await exchangeNpssoForCode(npsso);

// We can use the access code to get your access token and refresh token.
const authorization = await exchangeCodeForAccessToken(accessCode);

4. You should now be all set to use any endpoint provided by this package. Each function requires as its first argument an object containing your access token. ex:

const authorization = await exchangeCodeForAccessToken(accessCode);

// This returns a list of all the games you've earned trophies for.
const trophyTitlesResponse = await getUserTitles(
  { accessToken: authorization.accessToken },
  "me"
);

API

Click the function names to open their complete docs on the docs site.

Authentication

• exchangeCodeForAccessToken() - Exchange your access code for access and refresh tokens.
• exchangeNpssoForCode() - Exchange your NPSSO for an access code.
• exchangeRefreshTokenForAuthTokens() - Get a new access token using your refresh token (bypassing the need to constantly auth with your NPSSO).

Search

• makeUniversalSearch() - Search the PSN API. This is a good way to find a user's accountId from their username.

Trophies

• getTitleTrophies() - Retrieve the individual trophy details of a single or all trophy groups for a title.
• getTitleTrophyGroups() - Get a list of trophy groups (typically the base set and DLCs) for a title.
• getUserTitles() - Retrieve a list of the titles associated with an account and a summary of trophies earned from them.
• getUserTrophiesEarnedForTitle() - Retrieve the earned status of trophies for a user from either a single or all trophy groups in a title.
• getUserTrophyGroupEarningsForTitle() - Get a summary of trophies earned for a user broken down by trophy group within a title.
• getUserTrophyProfileSummary() - Retrieve an overall summary of the number of trophies earned for a user broken down by type.

Examples

• Build a user's complete trophy list and write it to a JSON file

Prior Art

Tustin/psn-php - A PHP wrapper for the PSN API
andshrew/PlayStation-Trophies - an attempt at documenting the PSN API by capturing the requests made by the PlayStation website

Disclaimer

This project is not intended to be used for spam or abuse. Please use this project to elevate the PlayStation Network experience, not damage it.

Contributors

Wes Copeland 💻 💡 📖

xelnia 🤔 📓

andshrew 📖

Susan Ma 📖