feat: add getSearchResults endpoint

.gitignore

@@ -14,6 +14,9 @@ coverage
 !.vscode/extensions.json
 !.vscode/settings.json
 
+# IntelliJ IDEA
+.idea/
+
 # Docusaurus
 website/node_modules
 website/.docusaurus

README.md

@@ -96,6 +96,7 @@ Click the function names to open their complete docs on the docs site.
 ### Search
 
 - [`makeUniversalSearch()`](https://psn-api.achievements.app/api-docs/universal-search#makeuniversalsearch) - Search the PSN API. This is a good way to find a user's `accountId` from their username.
+- [`getSearchResults()`](https://psn-api.achievements.app/api-docs/universal-search#getsearchresults) - Search for games, DLC, and other products on the PlayStation Store.
 
 ### Users
 

src/graphql/getSearchResults.test.ts

@@ -0,0 +1,205 @@
+import nock from "nock";
+
+import type { SearchResultsResponse } from "../models";
+import { getSearchResults } from "./getSearchResults";
+import { GRAPHQL_BASE_URL } from "./GRAPHQL_BASE_URL";
+
+describe("Function: getSearchResults", () => {
+  afterEach(() => {
+    nock.cleanAll();
+  });
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getSearchResults).toBeDefined();
+  });
+
+  it("retrieves search results for a given search term", async () => {
+    // ARRANGE
+    const mockResponse: SearchResultsResponse = {
+      data: {
+        universalSearch: {
+          __typename: "UniversalSearchResponse",
+          next: "CDAaVQolYjg5ODE2ODk0Y2ZiNDU2ZGIzNTU5MjIwOWM5YTdjODQtNDAxNxIsc2VhcmNoLXJlbGV2YW5jeS1jb25jZXB0LWdhbWUtYWxsLXRvcGstYXN0cmEiHnNlYXJjaC5ub19leHBlcmltZW50Lm5vbi4wLm5vbioDNzUx",
+          pageInfo: {
+            __typename: "PageInfo",
+            isLast: false,
+            offset: 0,
+            size: 2,
+            totalCount: 87
+          },
+          results: [
+            {
+              __typename: "Product",
+              id: "EP1018-CUSA00135_00-BAKPREORDER00001",
+              localizedStoreDisplayClassification: "Volledige game",
+              media: [
+                {
+                  __typename: "Media",
+                  role: "MASTER",
+                  type: "IMAGE",
+                  url: "https://image.api.playstation.com/cdn/EP1018/CUSA00135_00/gIBLibuNu1I91g9FYzkqBJFLMd1X9OaD.png"
+                }
+              ],
+              name: "Batman: Arkham Knight",
+              npTitleId: "CUSA00135_00",
+              personalizedMeta: {
+                __typename: "PersonalizedMeta",
+                hasMediaOverrides: false,
+                media: [
+                  {
+                    __typename: "Media",
+                    role: "MASTER",
+                    type: "IMAGE",
+                    url: "https://image.api.playstation.com/cdn/EP1018/CUSA00135_00/gIBLibuNu1I91g9FYzkqBJFLMd1X9OaD.png"
+                  }
+                ]
+              },
+              platforms: ["PS4"],
+              price: {
+                __typename: "SkuPrice",
+                skuId: "EP1018-CUSA00135_00-BAKPREORDER00001-E005",
+                basePrice: "€19.99",
+                discountText: null,
+                discountedPrice: null,
+                includesBundleOffer: null,
+                isExclusive: false,
+                isFree: false,
+                isTiedToSubscription: null,
+                serviceBranding: [],
+                upsellServiceBranding: [],
+                upsellText: null
+              },
+              skus: [
+                {
+                  __typename: "Sku",
+                  type: "STANDARD"
+                }
+              ],
+              storeDisplayClassification: "FULL_GAME"
+            },
+            {
+              __typename: "Product",
+              id: "EP1018-CUSA00135_00-DLCTWOFACESTORY0",
+              localizedStoreDisplayClassification: "Level",
+              media: [
+                {
+                  __typename: "Media",
+                  role: "MASTER",
+                  type: "IMAGE",
+                  url: "https://image.api.playstation.com/cdn/EP1018/CUSA00135_00/U2Yf57C14ovXI3zl3uXWoHSli3SywqEr.png"
+                }
+              ],
+              name: "Batman™: Arkham Knight Kop of munt",
+              npTitleId: "CUSA00135_00",
+              personalizedMeta: {
+                __typename: "PersonalizedMeta",
+                hasMediaOverrides: false,
+                media: [
+                  {
+                    __typename: "Media",
+                    role: "MASTER",
+                    type: "IMAGE",
+                    url: "https://image.api.playstation.com/cdn/EP1018/CUSA00135_00/U2Yf57C14ovXI3zl3uXWoHSli3SywqEr.png"
+                  }
+                ]
+              },
+              platforms: ["PS4"],
+              price: {
+                __typename: "SkuPrice",
+                skuId: "EP1018-CUSA00135_00-DLCTWOFACESTORY0-E001",
+                basePrice: "€1.99",
+                discountText: null,
+                discountedPrice: null,
+                includesBundleOffer: null,
+                isExclusive: false,
+                isFree: false,
+                isTiedToSubscription: null,
+                serviceBranding: [],
+                upsellServiceBranding: [],
+                upsellText: null
+              },
+              skus: [
+                {
+                  __typename: "Sku",
+                  type: "STANDARD"
+                }
+              ],
+              storeDisplayClassification: "LEVEL"
+            }
+          ]
+        }
+      }
+    };
+
+    const baseUrlObj = new URL(GRAPHQL_BASE_URL);
+    const baseUrl = `${baseUrlObj.protocol}//${baseUrlObj.host}`;
+    const basePath = baseUrlObj.pathname;
+
+    const cursor = "CDAaVQolYjg5ODE2ODk0Y2ZiNDU2ZGIzNTU5MjIwOWM5YTdjODQ";
+    const expectedVariables = JSON.stringify({
+      countryCode: "NL",
+      languageCode: "nl",
+      searchTerm: "batman",
+      pageSize: 2,
+      pageOffset: 0,
+      nextCursor: cursor
+    });
+    const expectedExtensions = JSON.stringify({
+      persistedQuery: {
+        version: 1,
+        sha256Hash:
+          "6ef5e809c35a056a1150fdcf513d9c505484dd1a946b6208888435c3182f105a"
+      }
+    });
+
+    // ... we need to use a nock matcher to verify the query parameters ...
+    const mockScope = nock(baseUrl)
+      .get(basePath)
+      .query((params) => {
+        expect(params.operationName).toEqual("getSearchResults");
+        expect(params.variables).toEqual(expectedVariables);
+        expect(params.extensions).toEqual(expectedExtensions);
+        return true;
+      })
+      .reply(200, mockResponse);
+
+    // ACT
+    const response = await getSearchResults("batman", {
+      countryCode: "NL",
+      languageCode: "nl",
+      pageSize: 2,
+      pageOffset: 0,
+      nextCursor: cursor
+    });
+
+    // ASSERT
+    expect(response).toEqual(mockResponse);
+    expect(mockScope.isDone()).toBeTruthy();
+  });
+
+  it("throws an error if we receive a malformed response", async () => {
+    // ARRANGE
+    const mockResponse = {
+      // This response occurs if the query/hash is not what the server expected.
+      message:
+        "Query 6ef5e809c35a056a1150fdcf513d9c505484dd1a946b6208888435c3182f105a not whitelisted"
+    };
+
+    const baseUrlObj = new URL(GRAPHQL_BASE_URL);
+    const baseUrl = `${baseUrlObj.protocol}//${baseUrlObj.host}`;
+    const basePath = baseUrlObj.pathname;
+
+    nock(baseUrl).get(basePath).query(true).reply(200, mockResponse);
+
+    // ASSERT
+    await expect(
+      getSearchResults("test", {
+        countryCode: "US",
+        languageCode: "en"
+      })
+    ).rejects.toThrow(
+      "Query 6ef5e809c35a056a1150fdcf513d9c505484dd1a946b6208888435c3182f105a not whitelisted"
+    );
+  });
+});

src/graphql/getSearchResults.ts

@@ -0,0 +1,72 @@
+import type { SearchResultsResponse } from "../models";
+import { call } from "../utils/call";
+import { GRAPHQL_BASE_URL } from "./GRAPHQL_BASE_URL";
+import { getSearchResultsHash } from "./operationHashes";
+
+type GetSearchResultsOptions = {
+  countryCode: string;
+  languageCode: string;
+  pageSize?: number;
+  pageOffset?: number;
+  nextCursor?: string;
+};
+
+/**
+ * A call to this function will retrieve search results from the PlayStation Store
+ * based on the provided search term and pagination.
+ *
+ * NOTE: This endpoint should be called WITHOUT authorization to receive price information.
+ * When called with authorization, price data may be filtered or unavailable.
+ *
+ * @param searchTerm The search term to query for.
+ * @param options An object containing search options.
+ * @param options.countryCode Two-letter country code (e.g., `"US"`, `"GB"`, `"NL"`) to determine region and pricing.
+ * @param options.languageCode Two-letter language code (e.g., `"en"`, `"es"`, `"nl"`) for localized content.
+ * @param options.pageSize _(Optional)_ Number of results per page.
+ * @param options.pageOffset _(Optional)_ Offset for pagination (0 for first page).
+ * @param options.nextCursor _(Optional)_ Pagination cursor.
+ */
+export const getSearchResults = async (
+  searchTerm: string,
+  options: GetSearchResultsOptions
+): Promise<SearchResultsResponse> => {
+  const { countryCode, languageCode, pageSize, pageOffset, nextCursor } = options;
+
+  const url = new URL(GRAPHQL_BASE_URL);
+
+  url.searchParams.set("operationName", "getSearchResults");
+
+  const variables: Record<string, unknown> = {
+    countryCode,
+    languageCode,
+    searchTerm,
+    ...(pageSize !== undefined && { pageSize }),
+    ...(pageOffset !== undefined && { pageOffset }),
+    ...(nextCursor !== undefined && { nextCursor })
+  };
+
+  url.searchParams.set("variables", JSON.stringify(variables));
+  url.searchParams.set(
+    "extensions",
+    JSON.stringify({
+      persistedQuery: {
+        version: 1,
+        sha256Hash: getSearchResultsHash
+      }
+    })
+  );
+
+  const response = await call<SearchResultsResponse>({
+    url: url.toString(),
+    headers: {
+      "Accept-Language": `${languageCode}-${countryCode}`
+    }
+  });
+
+  // The GraphQL queries can return non-truthy values.
+  if (!response.data || !response.data.universalSearch) {
+    throw new Error(JSON.stringify(response));
+  }
+
+  return response;
+};

src/graphql/index.ts

@@ -1,2 +1,3 @@
 export * from "./getPurchasedGames";
 export * from "./getRecentlyPlayedGames";
+export * from "./getSearchResults";

src/graphql/operationHashes.ts

@@ -22,3 +22,6 @@ export const getUserGameListHash =
 
 export const getPurchasedGameListHash =
   "827a423f6a8ddca4107ac01395af2ec0eafd8396fc7fa204aaf9b7ed2eefa168";
+
+export const getSearchResultsHash =
+  "6ef5e809c35a056a1150fdcf513d9c505484dd1a946b6208888435c3182f105a";

src/models/index.ts

@@ -12,6 +12,7 @@ export * from "./profile-from-user-name-response.model";
 export * from "./purchased-games-response.model";
 export * from "./rarest-thin-trophy.model";
 export * from "./recently-played-games-response.model";
+export * from "./search-results-response.model";
 export * from "./shareable-profile-link-response.model";
 export * from "./social-account-result.model";
 export * from "./title-platform.model";

src/models/search-results-response.model.ts

@@ -0,0 +1,65 @@
+export interface SearchResultMedia {
+  __typename: "Media";
+  role: string;
+  type: "IMAGE" | "VIDEO";
+  url: string;
+}
+
+export interface SearchResultPersonalizedMeta {
+  __typename: "PersonalizedMeta";
+  hasMediaOverrides: boolean;
+  media: SearchResultMedia[];
+}
+
+export interface SearchResultSkuPrice {
+  __typename: "SkuPrice";
+  skuId: string;
+  basePrice: string | null;
+  discountText: string | null;
+  discountedPrice: string | null;
+  includesBundleOffer: boolean | null;
+  isExclusive: boolean;
+  isFree: boolean;
+  isTiedToSubscription: boolean | null;
+  serviceBranding: string[];
+  upsellServiceBranding: string[];
+  upsellText: string | null;
+}
+
+export interface SearchResultSku {
+  __typename: "Sku";
+  type: string;
+}
+
+export interface SearchResultProduct {
+  __typename: "Product";
+  id: string;
+  name: string;
+  npTitleId: string;
+  platforms: string[];
+  localizedStoreDisplayClassification: string;
+  storeDisplayClassification: string;
+  media: SearchResultMedia[];
+  personalizedMeta: SearchResultPersonalizedMeta;
+  price: SearchResultSkuPrice;
+  skus: SearchResultSku[];
+}
+
+export interface SearchResultPageInfo {
+  __typename: "PageInfo";
+  isLast: boolean;
+  offset: number;
+  size: number;
+  totalCount: number;
+}
+
+export interface SearchResultsResponse {
+  data: {
+    universalSearch: {
+      __typename: "UniversalSearchResponse";
+      next: string | null;
+      pageInfo: SearchResultPageInfo;
+      results: SearchResultProduct[];
+    };
+  };
+}