@maixio/pstore 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 - 2026-05-09
+
+Initial public release of `@maixio/pstore`.
+
+- Added PlayStation Store lookup by Concept ID and Product ID.
+- Added lightweight search, category browse, and browse window commands.
+- Added built-in catalog UUID registry with validation and live discovery helpers.
+- Added multi-locale support for HK, TW, JP, US, GB, and CN storefronts.
+- Added optional Batarang page extraction for publisher, descriptions, content rating, and localized title metadata.
+- Added PlayStation Network status check command and SDK API.
+- Added TypeScript SDK entrypoint and `pstore` CLI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maixiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,515 @@
+# pstore
+
+Unofficial PlayStation Store Web API client for querying publicly available storefront metadata. It ships as both a CLI and a TypeScript SDK.
+
+> Disclaimer: pstore is a personal, unofficial project. It is not affiliated with, endorsed by, sponsored by, or authorized by Sony Interactive Entertainment, PlayStation, or any related company. PlayStation, PSN, and related marks are trademarks of their respective owners. The upstream PlayStation Store web APIs are not a public stable contract and may change without notice.
+
+Chinese documentation is available in [README.zh-CN.md](./README.zh-CN.md).
+
+## Quick Start
+
+```bash
+# Lookup a game
+pstore lookup 10014149
+
+# Search the store
+pstore search diablo
+
+# Browse a category
+pstore category pre-orders
+```
+
+## Installation
+
+Run directly:
+
+```bash
+bunx @maixio/pstore --help
+npx @maixio/pstore --help
+```
+
+Install globally:
+
+```bash
+bun add -g @maixio/pstore
+npm i -g @maixio/pstore
+pstore --help
+```
+
+Use as a library:
+
+```bash
+bun add @maixio/pstore
+```
+
+```ts
+import { createPstoreClient } from "@maixio/pstore";
+
+const pstore = createPstoreClient({ locale: "en-US" });
+
+const game = await pstore.lookup("10014149", {
+  includeProducts: true,
+});
+
+const search = await pstore.search({
+  term: "elden ring",
+  locale: "en-US",
+  size: 10,
+});
+
+const upcoming = await pstore.browse({
+  window: "next-thirty-days",
+  sortBy: "conceptReleaseDate",
+  order: "asc",
+  size: 10,
+});
+
+const deals = await pstore.categoryGrid({
+  id: "all-deals",
+  size: 10,
+});
+
+const status = await pstore.status();
+```
+
+## Public API
+
+| API | Description |
+| --- | --- |
+| `createPstoreClient(options)` | Creates a small SDK facade with a default locale. |
+| `lookupGame(id, options)` | Looks up a Concept ID or Product ID. |
+| `searchGames(options)` | Searches the store and returns lightweight fields available from PSN Search. |
+| `fetchBrowseGrid(query)` | Browses the store by time window, sorting, pagination, and filters. |
+| `fetchCategoryGridResult(params)` | Browses a catalog/category UUID or built-in alias and returns pagination, sort, and facet metadata. |
+| `fetchPsnStatus(options)` | Reads PlayStation Network service status. |
+| `discoverCatalogs(options)` | Discovers catalog UUIDs from the current storefront pages. |
+| `validateCatalogs(options)` | Validates whether built-in catalog UUIDs are still reachable. |
+| `clearPstoreCaches()` | Clears process-local lookup/search/category caches. |
+
+## API Notes
+
+- `lookupGame` detects Concept IDs and Product IDs from the ID shape.
+- `searchGames` intentionally avoids hidden N+1 enrichment by default. It does not fetch publisher, release date, genres, or localized titles unless you use `lookup`.
+- `fetchCategoryGridResult` accepts raw UUIDs. The SDK facade methods `category` and `categoryGrid` also accept built-in aliases.
+- `createPstoreClient({ locale })` stores only a default locale. Caches are process-local and shared.
+- The upstream PSN Web API has no public stability guarantee. Fields and persisted query hashes may drift when the web store changes.
+
+## CLI Overview
+
+```bash
+pstore lookup --help
+pstore search --help
+pstore category --help
+pstore browse --help
+pstore catalogs
+pstore status
+pstore config
+pstore init
+pstore clear-cache
+```
+
+## Output Fields
+
+Text and JSON output are projected from the same English field keys. `--json` only changes rendering. `--fields` limits output fields. `--select` limits output fields and, where possible, chooses a smaller lookup request plan.
+
+Common fields:
+
+- Lookup detail: `id`, `idType`, `conceptId`, `productId`, `name`, `locale`, `publisher`, `edition`, `releaseDate`, `price`, `rating`, `classification`, `topCategory`, `platforms`, `npTitleId`, `warnings`
+- Full lookup detail: `productName`, `genres`, `skus`, `descriptions`, `media`, `products`, `contentRating`, `localizedTitles`, `concept`, `sources`, `timing`
+- Search/category/browse default list fields: `id`, `name`, `type`, `price`, `platforms`, `classification`
+- Optional list field: `url`
+
+`search`, `category`, and `browse` do not output `url` by default because `id` is enough for `lookup` and scripts. Add it explicitly when needed:
+
+```bash
+pstore search astro --json --fields id,name,price,url
+pstore category all-deals --json --fields id,name,url
+pstore browse --window next-thirty-days --json --fields id,name,url
+```
+
+`lookup --select` can reduce upstream requests. For example, `--select id,name,price` skips rating, related products, and Batarang page requests. Selecting `publisher`, `descriptions`, or `contentRating` enables Batarang. For `search`, `category`, and `browse`, `--select` currently behaves like `--fields`.
+
+## lookup
+
+Looks up game details by Concept ID or Product ID. Comma-separated batch lookup is supported.
+
+Options:
+
+- `-l, --locale <locale>`: locale, defaulting to config
+- `-f, --fields <fields>`: comma-separated output fields
+- `--select <fields>`: field-driven request plan and output projection
+- `--full`: full detail profile with related products, concept data, and Batarang details
+- `-p, --products`: include related editions/products
+- `--with-concept`: include concept/default product data for Product ID lookups
+- `-b, --batarang`: force Batarang HTML extraction for descriptions, publisher, and page metadata
+- `--title-locales <locales>`: fetch localized titles; supports `cjk-en` or comma-separated locales
+- `-j, --json`: JSON output
+- `--verbose`: include timing information in text output
+- `--concurrency <count>`: batch lookup concurrency, default `3`
+
+Examples:
+
+```bash
+pstore lookup 10014149
+pstore lookup UP1001-PPSA28420_00-NBA2K26000000000
+pstore lookup 10014149,231761
+pstore lookup 10014149 --locale en-US
+pstore lookup 10014149 --json
+pstore lookup 10014149 --products
+pstore lookup 10014149 --title-locales cjk-en --json
+pstore lookup 10014149,10005069,10017939 --products --concurrency 2 --json
+pstore lookup 10014149 --fields id,name,price,rating
+pstore lookup 10014149 --select id,name,price --json
+```
+
+Lookup keeps PSN object semantics:
+
+- Product ID lookup uses `productRetrieve`; the top-level `price` belongs to that product/edition.
+- Concept ID lookup uses `conceptRetrieve`; the top-level `price` belongs to the concept/default product.
+- Product ID results expose the owning `conceptId`; use `--with-concept` when you need concept/default product details.
+- `--products` returns related editions under the same concept, and each `products[].price` remains that edition's own price.
+
+## category
+
+Browses a category by UUID or built-in alias.
+
+Options:
+
+- `-l, --locale <locale>`: locale
+- `-p, --page <page>`: page number, default `1`
+- `-s, --size <size>`: page size, default `24`
+- `--sort <sort>`: sort alias or raw field direction
+- `--filter <facet:key>`: generic facet filter, repeatable
+- `--platform <platform>`: platform filter, repeatable
+- `--genre <genre>`: genre filter, repeatable
+- `--classification <classification>`: product classification filter
+- `--price <range>`: price range, for example `0-0`
+- `--release <window>`: release window, for example `last_thirty_days`
+- `--vr <compatibility>`: VR compatibility filter
+- `--facets`: include supported facet metadata
+- `--sorts`: include supported sort metadata
+- `-f, --fields <fields>`: comma-separated output fields
+- `--select <fields>`: currently equivalent to `--fields`
+- `-j, --json`: JSON output
+
+Supported sort aliases:
+
+- `best-selling`
+- `downloads`
+- `name`
+- `name-desc`
+- `price-asc`
+- `price-desc`
+- `release-new`
+- `release-old`
+- `field:asc` / `field:desc`
+
+Examples:
+
+```bash
+pstore category pre-orders
+pstore category action
+pstore category rpg
+pstore category sports
+pstore category simulation
+pstore category all-deals
+pstore category 3bf499d7-7acf-4931-97dd-2667494ee2c9
+pstore category pre-orders --sort price-asc
+pstore category all-deals --size 3 --facets --sorts
+pstore category all-deals --platform PS5 --genre ACTION --price 0-0 --sort downloads
+pstore category pre-orders --page 2 --size 12
+pstore category pre-orders --json
+pstore category all-deals --fields id,name,url --json
+```
+
+## browse
+
+Browses PlayStation Store list semantics by time window, sorting, pagination, sampling, and generic filters.
+
+Options:
+
+- `-w, --window <window>`: `next-thirty-days`, `next_thirty_days`, `last-thirty-days`, `last_thirty_days`, or `all`
+- `--sort <sort>`: `conceptReleaseDate`, `sales30`, `downloads30`, `conceptName`, `webBasePrice`, or `contentCollections.contentCollectionStartDate`
+- `--order <order>`: `asc` or `desc`
+- `-p, --page <page>`: page number, default `1`
+- `-s, --size <size>`: page size, default `24`
+- `--sample <count>`: random sample count
+- `--filter <facet:value>`: generic raw PSN facet filter, repeatable
+- `--platform <value>`: platform filter, for example `PS5`
+- `--genre <value>`: genre filter, for example `ACTION`
+- `--price <range>`: price range, for example `0-0` or `10000-19999`
+- `--classification <value>`: classification filter, for example `FULL_GAME`
+- `--age-rating <value>`: age rating filter
+- `--vr <value>`: VR compatibility filter
+- `--notice <value>`: compatibility notice filter
+- `-f, --fields <fields>`: comma-separated output fields
+- `--select <fields>`: currently equivalent to `--fields`
+- `-l, --locale <locale>`: locale
+- `-j, --json`: JSON output
+
+Examples:
+
+```bash
+pstore browse --window next-thirty-days --sort conceptReleaseDate --order asc --sample 3
+pstore browse --window next-thirty-days --sort sales30 --order desc --sample 3
+pstore browse --window last-thirty-days --sort conceptReleaseDate --order desc --sample 3
+pstore browse --window last-thirty-days --sort sales30 --order desc --sample 3
+pstore browse --platform PS5 --genre ACTION --price 0-0
+pstore browse --filter conceptGenres:SPORTS --filter webBasePrice:10000-19999
+pstore browse --fields id,name,url --json
+```
+
+## search
+
+Searches games in the PlayStation Store.
+
+`search` returns only stable lightweight fields that are present in the PSN Search response. It does not enrich each result with detail calls. For publisher, release date, genres, localized titles, descriptions, or ratings, take an `id` from search results and call `lookup <id>`.
+
+Options:
+
+- `-l, --locale <locale>`: locale
+- `-p, --page <page>`: page number, default `1`
+- `-s, --size <size>`: page size, default `24`
+- `-f, --fields <fields>`: comma-separated output fields
+- `--select <fields>`: currently equivalent to `--fields`
+- `-j, --json`: JSON output
+
+Examples:
+
+```bash
+pstore search diablo
+pstore search "elden ring" --locale en-US
+pstore search "elden ring" --json
+pstore search "elden ring" --json --fields id,name,price,url
+pstore search "elden ring" --fields id,name,url
+pstore search game --page 2
+```
+
+## catalogs
+
+Lists built-in category aliases and UUIDs by default. The built-in table contains 58 relatively stable catalog UUIDs: 57 currently discoverable from storefront pages plus the hidden `all-deals` catalog. They are still upstream storefront data, so validate critical workflows before relying on them.
+
+Live discovery is also available:
+
+```bash
+pstore catalogs
+pstore catalogs --live --depth 1 --limit 50
+pstore catalogs --validate all-deals
+pstore catalogs --validate --json
+```
+
+In live output, `[from latest]` means the UUID was discovered from the `latest` navigation source page. It is a source marker, not the catalog title.
+
+## status
+
+Reads public JSON data from [status.playstation.com](https://status.playstation.com) to report PlayStation Network service status.
+
+```bash
+pstore status
+pstore status --locale en-US
+pstore status --country JP --json
+```
+
+## config / init
+
+```bash
+pstore config
+pstore init
+pstore clear-cache
+bun run live-smoke
+```
+
+Global color option:
+
+```bash
+pstore lookup 10014149 --no-color
+export NO_COLOR=1
+```
+
+## Supported Locales
+
+| Locale | Language | Region | Currency |
+| --- | --- | --- | --- |
+| `zh-hans-HK` | Simplified Chinese | Hong Kong | HK$ |
+| `zh-hant-HK` | Traditional Chinese | Hong Kong | HK$ |
+| `en-HK` | English | Hong Kong | HK$ |
+| `zh-hant-TW` | Traditional Chinese | Taiwan | NT$ |
+| `en-TW` | English | Taiwan | NT$ |
+| `ja-JP` | Japanese | Japan | ¥ |
+| `en-US` | English | United States | $ |
+| `en-GB` | English | United Kingdom | £ |
+| `zh-hans-CN` | Simplified Chinese | Mainland China | ¥ |
+
+## Field Reference
+
+CLI field names are English keys for scripts and SDK consumers.
+
+### Default Lookup Fields
+
+| Field | Type | Source | Description |
+| --- | --- | --- | --- |
+| `id` | string | derived | Primary result ID. |
+| `idType` | `"concept"` / `"product"` | derived | Result object type. |
+| `conceptId` | string | telemetry/price/rating/upsell | Owning concept ID. Product ID lookups try to fill this as well. |
+| `productId` | string | telemetry/price/rating/upsell | Current product ID or default product ID for a concept. |
+| `name` | string | telemetry/batarang | Game title. |
+| `locale` | string | input | Current locale. |
+| `publisher` | string | batarang | Publisher. The default detail profile attempts to fetch it. |
+| `edition` | string | telemetry | Edition name. |
+| `releaseDate` | string | telemetry/rating/batarang | ISO 8601 release date. |
+| `price` | object | price/telemetry | Top-level price. Product ID means product price; Concept ID means default product price. |
+| `rating` | object | rating/batarang | Rating summary without `ratingsDistribution`. |
+| `platforms` | string[] | telemetry/upsell/batarang | Platform list. |
+| `genres` | string[] | telemetry/batarang | Localized genres. |
+| `localizedTitles` | object | lookup by locale | Multi-locale titles. Defaults to the `cjk-en` preset. |
+| `warnings` | object[] | runtime | Non-fatal data source failures. |
+
+### Full Lookup Fields
+
+| Field | Type | Source | Description |
+| --- | --- | --- | --- |
+| `productName` | string | telemetry | Product-level title. |
+| `skus` | object[] | telemetry | SKU data. |
+| `descriptions` | object[] | batarang | Short description, long description, compatibility notices, and legal text. |
+| `media` | object[] | upsell/batarang | Screenshots, videos, and storefront images. |
+| `products` | object[] | upsell | Related editions under the same concept; each product keeps its own `price`. |
+| `contentRating` | object | telemetry/batarang | Content rating. |
+| `concept` | object | lookup | Extra concept/default product data for Product ID lookups with `--with-concept`. |
+| `sources` | object | runtime | Source tracking for important fields. |
+| `timing` | object | runtime | Per-source timings. |
+| `npTitleId` | string | telemetry/batarang | PSN title id. It is not in the default detail profile; select it with `--fields npTitleId`. |
+
+### Search / Category / Browse List Fields
+
+| Field | Type | Default | Source | Description |
+| --- | --- | --- | --- | --- |
+| `id` | string | Yes | search/category grid | Concept ID or Product ID; use with `type`. |
+| `name` | string | Yes | search/category grid | Localized title. |
+| `type` | `"concept"` / `"product"` | Yes | `__typename` | List item type. |
+| `price` | string/null | Yes | search/category grid | Current display price. |
+| `platforms` | string[]/null | Yes | search/category grid | Platform list. |
+| `classification` | string/null | Yes | search/category grid | Localized product classification, such as full game or deluxe edition. |
+| `url` | string | No | derived | Store URL; explicitly request it with `--fields id,name,url`. |
+
+Use `lookup --batarang`, `lookup --full`, or a detail-oriented `lookup --select` when you need descriptions, publisher, ratings, or content rating. `search` avoids default enrichment to prevent slow N+1 request patterns.
+
+## Category Aliases
+
+| Alias | UUID | Description |
+| --- | --- | --- |
+| `all-deals` | `3f772501-...` | All deals, hidden catalog |
+| `all-games` | `28c9c2b2-...` | All games |
+| `all-ps5-games` | `d0446d4b-...` | All PS5 games |
+| `all-ps4-games` | `30e3fe35-...` | All PS4 games |
+| `pre-orders` | `3bf499d7-...` | Pre-orders |
+| `add-ons` | `51c9aa7a-...` | Add-ons |
+| `free-to-play` | `4dfd67ab-...` | Free-to-play |
+| `best-sellers` | `132bb05e-...` | Best sellers |
+| `new-games` | `e1699f77-...` | New games |
+| `action` | `298b428c-...` | Action games |
+| `rpg` | `e0b1cde3-...` | Role-playing games |
+| `shooter` | `64ee024b-...` | Shooter games |
+| `sports` | `b86f0f65-...` | Sports games |
+| `racing` | `b78c6346-...` | Racing games |
+| `fighting` | `0f6fc626-...` | Fighting games |
+| `simulation` | `bb42a4e0-...` | Simulation games |
+
+The complete list is available through `pstore catalogs` and the exported `BUILTIN_CATALOGS`.
+
+## Configuration
+
+pstore reads `pstore.config.json` as the default config file.
+
+Lookup order:
+
+1. `./pstore.config.json`
+2. `./psn-config.json` for legacy compatibility
+3. `~/.config/pstore/config.json`
+4. `~/.config/psn-cli/config.json` for legacy compatibility
+
+Default config:
+
+```json
+{
+  "locale": "zh-hans-HK",
+  "format": "text",
+  "pageSize": 24,
+  "verbose": false,
+  "color": true,
+  "cacheTtl": {
+    "lookup": 300000,
+    "search": 120000,
+    "category": 120000
+  }
+}
+```
+
+Fields:
+
+- `locale`: default locale.
+- `format`: default output format, `text` or `json`.
+- `pageSize`: default page size for `search`, `category`, and `browse`, from `1` to `100`.
+- `verbose`: whether lookup text output includes timing by default.
+- `color`: whether colored output is enabled by default.
+- `cacheTtl.lookup/search/category`: in-memory cache TTL in milliseconds.
+
+Generate a config file:
+
+```bash
+pstore init
+```
+
+## Technical Notes
+
+- Uses PSN GraphQL persisted query APIs without login.
+- Detail lookup combines telemetry, price, rating, upsell, and optional Batarang HTML sources.
+- Product IDs map to PSN `productRetrieve`; the top-level price is the current product/edition CTA price.
+- Concept IDs map to PSN `conceptRetrieve`; the top-level price is the default product CTA price.
+- `conceptRetrieveForUpsellWithCtas` returns multiple editions/products, and pstore preserves each `products[].price`.
+- HTTP timeout is 10 seconds, with 2 default retries. `429` and `5xx` responses back off and respect `Retry-After`.
+- Batch lookup defaults to 3 concurrent requests and can be tuned with `--concurrency`.
+- Process-local TTL caching covers lookup, search, and category calls.
+- Batarang HTML data is extracted from SSR pages without a browser.
+- Product ID results keep the product as the primary object and expose `conceptId`; use `--with-concept` for concept/default product details.
+
+## Scripting Tips
+
+Prefer JSON output for automation:
+
+```bash
+pstore lookup 10005069 --products --title-locales cjk-en --json
+pstore search "Saros" --locale en-US --json --fields id,name,price,url
+pstore browse --window next-thirty-days --sort conceptReleaseDate --order asc --sample 3 --json --fields id,name,price,url
+```
+
+Recommendations:
+
+- Always use `--json` and inspect `warnings` for partial data source failures.
+- For product details, treat top-level `price` as that product's price. For concept details, treat top-level `price` as the default product price and `products[].price` as each edition's price.
+- Use `--concurrency 2` or `--concurrency 3` for batch lookup to reduce the chance of `429` responses.
+- Use `--title-locales cjk-en` when you need multi-locale titles.
+- Use `--batarang` when you need descriptions, publisher, or content rating.
+- Do not depend on text output order; depend on JSON keys.
+
+## Logs
+
+API request logs are written to `logs/pstore-YYYY-MM-DD.log`, including request timings and outcomes.
+
+## Testing
+
+```bash
+bun test
+bunx tsc --noEmit
+bun run live-smoke
+bun run test:live
+bun run test:live:locales
+bun run test:live:full
+PSTORE_SMOKE_LOCALES=zh-hans-HK,en-US,ja-JP,zh-hant-TW,en-TW bun run live-smoke
+PSTORE_SMOKE_FULL=1 bun run live-smoke
+```
+
+The test suite covers unit tests, API response fixtures, CLI/package contracts, performance checks, and edge cases. `live-smoke` checks the default locale by default. Use `PSTORE_SMOKE_LOCALES` and `PSTORE_SMOKE_FULL=1` to broaden live coverage when checking for persisted query hash or field shape drift.
+
+## License
+
+MIT