psn-api

PSN API

A low-level API for getting 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, supports tree-shaking.
✅  Aligns with the community PSN API documentation.
✅  Supports Node environments (14 and above).
✅  Supports browsers.
✅  Ships with TypeScript support and types.
✅  Tiny, <2Kb.

---

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 { getTrophiesEarnedForTitle } 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((accessTokenResponse) => {
  console.log({ accessTokenResponse });
});

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

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://my.playstation.com/ 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":"Hwl9Vq..."}

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

1. 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 = "Hwl9Vq...";

// 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);

1. 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 getTrophyTitlesForUser(
  { accessToken: authorization.accessToken },
  "me"
);

API

Click the function names for complete docs.

Authentication

• exchangeCodeForAccessToken() - Exchange your access code for access and refresh tokens.
• exchangeNpssoForCode() - Exchange your NPSSO for an access code.

Trophies

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

Examples

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

How to contribute

Prerequisites

Before beginning, please make sure you have the following tools installed.

• Node.js (the latest LTS release, download)
• yarn classic (1.x, instructions)

Installation

git clone https://github.com/achievements-app/psn-api.git
cd psn-api
yarn

Local development

Start a local dev server in watch mode with yarn dev.

There is a dev playground set up in src/__dev-playground.ts. When changes are made to this file, you will see updates in your terminal.

Tests can be executed using yarn test.

Contributors