@maixio/pstore 0.1.0

package/README.zh-CN.md

@@ -0,0 +1,610 @@
+# pstore
+
+pstore 是一个非官方的 PlayStation Store Web API 客户端封装，提供 CLI 和 TypeScript SDK，用于查询公开可访问的商店游戏信息、搜索结果、分类列表和 PSN 服务状态。
+
+> 免责声明: 本项目是个人维护的非官方工具，不隶属于 Sony Interactive Entertainment、PlayStation 或其关联公司，也未获得其认可、赞助或授权。PlayStation、PSN 及相关商标归其各自权利方所有。接口行为可能随 PlayStation Store Web 端变化而变化。
+
+Unofficial PlayStation Store CLI and SDK for publicly available storefront metadata. This project is not affiliated with, endorsed by, sponsored by, or authorized by Sony Interactive Entertainment or PlayStation.
+
+## 快速开始
+
+```bash
+# 查询游戏
+pstore lookup 10014149
+
+# 搜索
+pstore search diablo
+
+# 分类浏览
+pstore category pre-orders
+```
+
+## 安装
+
+```bash
+# 直接运行
+bunx @maixio/pstore --help
+npx @maixio/pstore --help
+
+# 全局安装
+bun add -g @maixio/pstore
+npm i -g @maixio/pstore
+pstore --help
+```
+
+作为库使用：
+
+```bash
+bun add @maixio/pstore
+```
+
+```ts
+import { createPstoreClient } from "@maixio/pstore";
+
+const pstore = createPstoreClient({ locale: "zh-hans-HK" });
+
+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 | 说明 |
+|-----|------|
+| `createPstoreClient(options)` | 创建带默认 locale 的 SDK facade。 |
+| `lookupGame(id, options)` | 查询单个 Concept ID 或 Product ID 的详情。 |
+| `searchGames(options)` | 按关键词搜索商店，返回 PSN Search 原始结果中的轻量字段。 |
+| `fetchBrowseGrid(query)` | 按 browse 时间窗、排序和筛选浏览列表。 |
+| `fetchCategoryGridResult(params)` | 按 catalog UUID 或别名浏览分类，并返回分页、排序和 facet 元数据。 |
+| `fetchPsnStatus(options)` | 查询 PlayStation Network 服务状态。 |
+| `discoverCatalogs(options)` | 从当前商店页面实时发现 catalog UUID。 |
+| `validateCatalogs(options)` | 验证内置 catalog UUID 是否仍可访问。 |
+| `clearPstoreCaches()` | 清空进程内 lookup/search/category 缓存。 |
+
+### API Notes
+
+- `lookupGame` 会根据 ID 形态自动区分 Concept ID 和 Product ID。
+- `searchGames` 默认不做详情增强，不额外请求 publisher、releaseDate、genres 等详情字段。
+- `fetchCategoryGridResult` 支持直接传 UUID；SDK facade 的 `category` / `categoryGrid` 也支持内置别名。
+- `createPstoreClient({ locale })` 只保存默认 locale；缓存仍是进程级共享缓存。
+- 上游 PSN Web API 没有公开稳定合约，字段和 persisted query hash 可能随商店前端更新而变化。
+
+## 使用
+
+### 命令总览
+
+```bash
+pstore lookup --help
+pstore search --help
+pstore category --help
+pstore browse --help
+pstore catalogs
+pstore status
+pstore config
+pstore init
+pstore clear-cache
+```
+
+### 输出字段
+
+文本和 JSON 输出使用同一套英文字段选择。`--json` 只改变渲染格式，`--fields` 只裁剪输出字段，`--select` 会同时裁剪输出并尽量按字段选择请求计划。
+
+常用字段:
+
+- 详情: `id`, `idType`, `conceptId`, `productId`, `name`, `locale`, `publisher`, `edition`, `releaseDate`, `price`, `rating`, `classification`, `topCategory`, `platforms`, `npTitleId`, `warnings`
+- 完整详情: `productName`, `genres`, `skus`, `descriptions`, `media`, `products`, `contentRating`, `localizedTitles`, `concept`, `sources`, `timing`
+- 搜索/列表默认: `id`, `name`, `type`, `price`, `platforms`, `classification`
+- 可显式选择: `url`
+
+`search`、`category`、`browse` 默认不输出 `url`，因为 `id` 已足够给 `lookup` 或后续脚本使用；需要商店链接时显式加 `--fields id,name,url`。
+
+`lookup --select` 会根据字段生成更小的请求计划。例如 `--select id,name,price` 不会请求评分、关联版本和 Batarang 页面；`--select publisher`、`--select descriptions`、`--select contentRating` 会启用 Batarang。`search`、`category`、`browse` 的 `--select` 当前等同 `--fields`，只影响输出字段，不改变上游请求。
+
+```bash
+pstore lookup 10014149 --json --fields id,name,price,platforms
+pstore lookup 10014149 --json --select id,name,price
+pstore lookup 10014149 --full --json
+pstore search astro --json --fields id,name,price,url
+pstore browse --window next-thirty-days --json --fields id,name,price,url
+```
+
+### lookup — 查询游戏详情
+
+查询游戏详情，支持 Concept ID 或 Product ID，也支持逗号分隔的批量查询。
+
+参数:
+- `<ids>`: `Concept ID` 或 `Product ID`，多个值可用逗号分隔
+
+选项:
+- `-l, --locale <locale>`: 默认语言区域，未指定时使用配置文件中的 `locale`
+- `-f, --fields <fields>`: 仅输出指定英文字段，字段之间用逗号分隔
+- `--select <fields>`: 字段驱动请求计划并输出指定字段，例如 `id,name,price`
+- `--full`: 输出完整字段 profile，并启用关联版本、concept、Batarang 详情请求
+- `-p, --products`: 包含关联版本
+- `--with-concept`: Product ID 查询时额外返回所属 concept/default product 信息
+- `-b, --batarang`: 强制爬取 Batarang HTML，以获取描述、发行商等信息
+- `--title-locales <locales>`: 同时返回多区域标题；支持 `cjk-en` 或逗号分隔 locale 列表
+- `-j, --json`: JSON 输出
+- `--verbose`: 显示时间分布
+- `--concurrency <count>`: 批量查询并发数，默认 `3`
+
+示例:
+
+```bash
+# 按 Concept ID 查询
+pstore lookup 10014149
+
+# 按 Product ID 查询
+pstore lookup UP1001-PPSA28420_00-NBA2K26000000000
+
+# 多个 ID 批量查询
+pstore lookup 10014149,231761
+
+# 指定语言
+pstore lookup 10014149 --locale en-HK
+
+# JSON 输出
+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 会保留 PSN 官方 API 的对象语义：
+
+- Product ID 走 `productRetrieve`，顶层 `price` 是该 product/edition 自己的价格。
+- Concept ID 走 `conceptRetrieve`，顶层 `price` 是 concept/default product 的主价格。
+- Product ID 查询会在 `conceptId` 字段暴露所属 concept；需要完整 concept/default product 数据时使用 `--with-concept`。
+
+`--products` 会返回同 concept 下的关联版本：
+
+- `products[].price` 是每个 edition/product 自己的价格。
+
+例如 `concept/10005069`：
+
+```json
+{
+  "price": { "discountedPrice": "HK$568.00" },
+  "products": [
+    {
+      "id": "HP9000-PPSA07634_00-SAROS00000000000",
+      "edition": { "name": "普通版" },
+      "price": { "discountedPrice": "HK$568.00" }
+    },
+    {
+      "id": "HP9000-PPSA07634_00-SAROSDELUXE00000",
+      "edition": { "name": "数字豪华版" },
+      "price": { "discountedPrice": "HK$628.00" }
+    }
+  ]
+}
+```
+
+### category — 分类浏览
+
+按分类 UUID 或内置别名浏览商品列表。
+
+参数:
+- `<id>`: 分类 UUID 或别名，例如 `pre-orders`
+
+选项:
+- `-l, --locale <locale>`: 默认语言区域
+- `-p, --page <page>`: 页码，默认 `1`
+- `-s, --size <size>`: 每页数量，默认 `24`
+- `--sort <sort>`: 排序方式
+- `--filter <facet:key>`: 通用筛选，可重复，例如 `productGenres:ACTION`
+- `--platform <platform>`: 按平台筛选，可重复，例如 `PS5`
+- `--genre <genre>`: 按类型筛选，可重复，例如 `ACTION`
+- `--classification <classification>`: 按商品类型筛选，例如 `FULL_GAME`
+- `--price <range>`: 按价格区间筛选，例如 `0-0`
+- `--release <window>`: 按推出日期筛选，例如 `last_thirty_days`
+- `--vr <compatibility>`: 按 VR 兼容筛选，例如 `PSVR2`
+- `--facets`: 在 JSON/文本输出中包含当前分类支持的筛选项
+- `--sorts`: 在 JSON/文本输出中包含当前分类支持的排序项
+- `-f, --fields <fields>`: 仅输出指定英文字段，字段之间用逗号分隔
+- `--select <fields>`: 字段驱动输出，当前等同 `--fields`
+- `-j, --json`: JSON 输出
+
+支持的排序值:
+- `best-selling`
+- `downloads`
+- `name`
+- `name-desc`
+- `price-asc`
+- `price-desc`
+- `release-new`
+- `release-old`
+- `field:asc` / `field:desc`
+
+示例:
+
+```bash
+# 基本分类浏览
+pstore category pre-orders
+pstore category action
+pstore category rpg
+pstore category sports
+pstore category simulation
+pstore category all-deals
+
+# 使用 UUID
+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
+
+# JSON 输出
+pstore category pre-orders --json
+
+# 只输出 ID、标题、商店 URL
+pstore category all-deals --fields id,name,url --json
+```
+
+### browse — 浏览首页/时间窗页面
+
+按 PlayStation Store 的 `browse` 页面语义浏览列表。当前支持时间窗、排序、分页、随机抽样，以及通用筛选。
+
+选项:
+- `-w, --window <window>`: 时间窗口，可用值包括 `next-thirty-days`、`next_thirty_days`、`last-thirty-days`、`last_thirty_days`、`all`
+- `--sort <sort>`: 排序字段，可用值包括 `conceptReleaseDate`、`sales30`、`downloads30`、`conceptName`、`webBasePrice`、`contentCollections.contentCollectionStartDate`
+- `--order <order>`: 排序方向，可用值包括 `asc`、`desc`
+- `-p, --page <page>`: 页码，默认 `1`
+- `-s, --size <size>`: 每页数量，默认 `24`
+- `--sample <count>`: 随机抽样条目数，默认不抽样
+- `--filter <facet:value>`: 通用筛选，可重复，任意 `facet:value` 都会原样传给 PSN API
+- `--platform <value>`: 平台筛选，例如 `PS5`、`PS4`
+- `--genre <value>`: 类型筛选，例如 `ACTION`、`SPORTS`
+- `--price <range>`: 价格筛选，例如 `0-0`、`10000-19999`
+- `--classification <value>`: 分类筛选，例如 `FULL_GAME`
+- `--age-rating <value>`: 年龄分级筛选
+- `--vr <value>`: VR 兼容性筛选
+- `--notice <value>`: 兼容性提示筛选
+- `-f, --fields <fields>`: 仅输出指定英文字段，字段之间用逗号分隔
+- `--select <fields>`: 字段驱动输出，当前等同 `--fields`
+- `-l, --locale <locale>`: 默认语言区域
+- `-j, --json`: JSON 输出
+
+示例:
+
+```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
+
+# 原样透传任意 facet:value
+pstore browse --filter conceptGenres:SPORTS --filter webBasePrice:10000-19999
+
+# 只输出 ID、标题、商店 URL
+pstore browse --fields id,name,url --json
+```
+
+### search — 搜索游戏
+
+按关键词搜索 PSN 商店中的游戏。
+
+`search` 默认只返回 PSN Search 原始结果中稳定可得的轻量字段，不会额外请求详情接口。需要发行商、发售日期、游戏类型、多语言标题等详情时，先取搜索结果的 `id`，再使用 `lookup <id>`。
+
+参数:
+- `<term>`: 搜索关键词
+
+选项:
+- `-l, --locale <locale>`: 默认语言区域
+- `-p, --page <page>`: 页码，默认 `1`
+- `-s, --size <size>`: 每页数量，默认 `24`
+- `-f, --fields <fields>`: 仅输出指定英文字段，字段之间用逗号分隔
+- `--select <fields>`: 字段驱动输出，当前等同 `--fields`
+- `-j, --json`: JSON 输出
+
+示例:
+
+```bash
+# 基本搜索
+pstore search diablo
+
+# 指定语言
+pstore search 原神 --locale zh-hans-HK
+
+# JSON 输出
+pstore search "elden ring" --json
+
+# JSON 输出并裁剪字段
+pstore search "elden ring" --json --fields id,name,price,url
+
+# 只输出 ID、标题、商店 URL
+pstore search "elden ring" --fields id,name,url
+
+# 分页
+pstore search game --page 2
+```
+
+### catalogs — 列出内置分类别名 / 实时发现 catalog
+
+默认显示当前内置的分类别名和对应 UUID。内置表包含当前导航页可发现的 57 个 catalog，以及页面不可直接扫出的隐藏 `all-deals`，共 58 个。UUID 相对稳定，但它们仍属于 PSN 商店数据，严肃使用前建议用 `--validate` 抽样验证。
+
+也可以使用 `--live` 从当前 PSN 页面入口实时爬取 catalog UUID：
+
+```bash
+pstore catalogs
+pstore catalogs --live --depth 1 --limit 50
+pstore catalogs --validate all-deals
+pstore catalogs --validate --json
+```
+
+`--live` 输出里的 `[from latest]` 表示该 UUID 是从 `latest` 导航入口页面发现的来源标记，不代表 catalog 的标题。
+
+### status — 查询 PlayStation Network 服务状态
+
+`status` 命令读取 [status.playstation.com](https://status.playstation.com) 的公开配置和区域状态 JSON，用来判断当前 PSN 服务是否存在维护、降级或中断。
+
+```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
+```
+
+### 全局选项
+
+- `--no-color`: 禁用彩色输出
+
+```bash
+# 禁用彩色输出
+pstore lookup 10014149 --no-color
+
+# 或设置环境变量
+export NO_COLOR=1
+```
+
+## 支持的区域
+
+| Locale | 语言 | 地区 | 货币 |
+|--------|------|------|------|
+| `zh-hans-HK` | 简体中文 | 香港 | HK$ |
+| `zh-hant-HK` | 繁體中文 | 香港 | HK$ |
+| `en-HK` | English | 香港 | HK$ |
+| `zh-hant-TW` | 繁體中文 | 台湾 | NT$ |
+| `en-TW` | English | 台湾 | NT$ |
+| `ja-JP` | 日本語 | 日本 | ¥ |
+| `en-US` | English | 美国 | $ |
+| `en-GB` | English | 英国 | £ |
+| `zh-hans-CN` | 简体中文 | 中国大陆 | ¥ |
+
+## 字段说明
+
+CLI 字段名统一使用英文 key，便于脚本和开发者消费。文本输出仍会显示中文标签，但 `--fields` / `--select` 应使用英文 key。
+
+### Lookup 默认字段
+
+| 字段 | 类型 | 来源 | 说明 |
+|------|------|------|------|
+| `id` | string | derived | 当前结果主 ID。 |
+| `idType` | `"concept"` / `"product"` | derived | 当前结果对象类型。 |
+| `conceptId` | string | telemetry/price/rating/upsell | 所属 concept ID，Product ID 查询时也会尽量补齐。 |
+| `productId` | string | telemetry/price/rating/upsell | 当前 product ID 或 concept 的 default product ID。 |
+| `name` | string | telemetry/batarang | 游戏标题。 |
+| `locale` | string | input | 当前语言区域。 |
+| `publisher` | string | batarang | 发行商；默认 detail profile 会尝试获取。 |
+| `edition` | string | telemetry | 版本名。 |
+| `releaseDate` | string | telemetry/rating/batarang | ISO 8601 发售日期。 |
+| `price` | object | price/telemetry | 顶层价格；Product ID 为该 product 价格，Concept ID 为 default product 价格。 |
+| `rating` | object | rating/batarang | 星级评分摘要，不包含 `ratingsDistribution`。 |
+| `platforms` | string[] | telemetry/upsell/batarang | 平台列表。 |
+| `genres` | string[] | telemetry/batarang | 本地化游戏类型。 |
+| `localizedTitles` | object | lookup by locale | 多区域标题；默认使用 `cjk-en` 预设。 |
+| `warnings` | object[] | runtime | 非致命数据源失败。 |
+
+### Lookup 完整字段
+
+| 字段 | 类型 | 来源 | 说明 |
+|------|------|------|------|
+| `productName` | string | telemetry | 商品级标题。 |
+| `skus` | object[] | telemetry | SKU 信息。 |
+| `descriptions` | object[] | batarang | 短描述、长描述、兼容性说明和法律文本。 |
+| `media` | object[] | upsell/batarang | 截图、视频和商店图片。 |
+| `products` | object[] | upsell | 同一 concept 下的关联版本；每个版本保留自己的 `price`。 |
+| `contentRating` | object | telemetry/batarang | 年龄分级。 |
+| `concept` | object | lookup | Product ID 查询时通过 `--with-concept` 返回的 concept/default product 补充数据。 |
+| `sources` | object | runtime | 关键字段来源。 |
+| `timing` | object | runtime | 各数据源耗时。 |
+| `npTitleId` | string | telemetry/batarang | PSN title id；默认 detail profile 不输出，可用 `--fields npTitleId` 选择。 |
+
+### Search / Category / Browse 列表字段
+
+| 字段 | 类型 | 默认 | 来源 | 说明 |
+|------|------|------|------|------|
+| `id` | string | 是 | search/category grid | Concept ID 或 Product ID；结合 `type` 判断。 |
+| `name` | string | 是 | search/category grid | 本地化标题。 |
+| `type` | `"concept"` / `"product"` | 是 | `__typename` | 列表项类型。 |
+| `price` | string/null | 是 | search/category grid | 当前显示价格。 |
+| `platforms` | string[]/null | 是 | search/category grid | 平台列表。 |
+| `classification` | string/null | 是 | search/category grid | 本地化商品类型，例如制品版游戏、豪华版。 |
+| `url` | string | 否 | derived | 商店链接；需要时显式 `--fields id,name,url`。 |
+
+> 需要描述、发行商、内容分级等页面详情时使用 `lookup --batarang`、`lookup --full` 或对应 `lookup --select` 字段。`search` 默认不做详情增强，以避免 N+1 请求。
+
+## 分类别名
+
+| 别名 | UUID | 说明 |
+|------|------|------|
+| `all-deals` | `3f772501-...` | 所有优惠，隐藏 catalog |
+| `all-games` | `28c9c2b2-...` | 所有游戏 |
+| `all-ps5-games` | `d0446d4b-...` | 所有 PS5 游戏 |
+| `all-ps4-games` | `30e3fe35-...` | 所有 PS4 游戏 |
+| `pre-orders` | `3bf499d7-...` | 预购游戏 |
+| `add-ons` | `51c9aa7a-...` | 追加内容 |
+| `free-to-play` | `4dfd67ab-...` | 基本免费游戏 |
+| `best-sellers` | `132bb05e-...` | 最畅销 |
+| `new-games` | `e1699f77-...` | 新的游戏 |
+| `action` | `298b428c-...` | 动作游戏 |
+| `rpg` | `e0b1cde3-...` | 角色扮演 |
+| `shooter` | `64ee024b-...` | 射击游戏 |
+| `sports` | `b86f0f65-...` | 体育游戏 |
+| `racing` | `b78c6346-...` | 赛车游戏 |
+| `fighting` | `0f6fc626-...` | 格斗游戏 |
+| `simulation` | `bb42a4e0-...` | 模拟游戏 |
+
+完整列表以 `pstore catalogs` 和导出的 `BUILTIN_CATALOGS` 为准。
+
+## 配置文件
+
+pstore 会读取 `pstore.config.json` 作为默认配置文件。
+
+查找顺序:
+1. 当前项目目录下的 `./pstore.config.json`
+2. 当前项目目录下的 `./psn-config.json`（旧配置兼容）
+3. 用户目录下的 `~/.config/pstore/config.json`
+4. 用户目录下的 `~/.config/psn-cli/config.json`（旧配置兼容）
+
+默认内容:
+
+```json
+{
+  "locale": "zh-hans-HK",
+  "format": "text",
+  "pageSize": 24,
+  "verbose": false,
+  "color": true,
+  "cacheTtl": {
+    "lookup": 300000,
+    "search": 120000,
+    "category": 120000
+  }
+}
+```
+
+字段说明:
+- `locale`: 默认语言区域。
+- `format`: 默认输出格式，`text` 或 `json`。
+- `pageSize`: `search`、`category`、`browse` 的默认页大小，范围 `1-100`。
+- `verbose`: lookup 文本输出是否默认展示耗时。
+- `color`: 是否默认使用彩色输出。
+- `cacheTtl.lookup/search/category`: 内存缓存 TTL，单位毫秒。
+
+生成配置文件:
+
+```bash
+pstore init
+```
+
+## 技术说明
+
+- 使用 PSN GraphQL persisted query API（无需登录）。
+- 详情页由多个 operation 组合：telemetry、price、rating、upsell，以及可选 Batarang HTML。
+- product ID 对应 PSN `productRetrieve`；顶层价格表示该 product/edition 的 CTA 价格。
+- concept ID 对应 PSN `conceptRetrieve`；顶层价格表示 default product 主 CTA 价格。
+- `conceptRetrieveForUpsellWithCtas` 返回多个 edition/product，项目会保留每个 `products[].price`。
+- HTTP 超时 10s，默认重试 2 次；429/5xx 会退避，并尊重 `Retry-After`。
+- 批量 lookup 默认 3 并发，可通过 `--concurrency` 调整。
+- 内存 TTL 缓存覆盖 lookup、search、category。
+- Batarang HTML 数据通过 SSR 页面提取（无需浏览器）。
+- Product ID 结果会保留 product 作为主对象，并通过 `conceptId` 标明所属 concept；需要 concept/default product 详情时使用 `--with-concept`。
+
+## 给脚本使用的建议
+
+普通 CLI 也适合脚本调用，只要始终使用 JSON 输出：
+
+```bash
+pstore lookup 10005069 --products --title-locales cjk-en --json
+pstore search "Saros" --locale zh-hans-HK --json --fields id,name,price,url
+pstore browse --window next-thirty-days --sort conceptReleaseDate --order asc --sample 3 --json --fields id,name,price,url
+```
+
+建议：
+
+- 始终加 `--json`，并读取 `warnings` 字段判断结果是否部分缺失。
+- 查 product 详情时，使用顶层 `price` 作为该 product 价格；查 concept 详情时，使用顶层 `price` 作为 default product 价格，使用 `products[].price` 作为各版本价格。
+- 批量 lookup 使用 `--concurrency 2` 或 `--concurrency 3`，降低触发 429 的概率。
+- 需要多语言标题时使用 `--title-locales cjk-en`。
+- 需要描述、发行商、内容分级等页面详情时加 `--batarang`。
+- 不要依赖文本字段顺序；以 JSON key 为准。
+
+## 日志
+
+API 请求日志自动写入 `logs/pstore-YYYY-MM-DD.log`，包含每次请求的耗时和结果。
+
+## 测试
+
+```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
+```
+
+当前测试覆盖单元测试、API 响应结构验证、CLI/包契约、性能基准测试、极端场景测试。`live-smoke` 默认只检查默认区域；通过 `PSTORE_SMOKE_LOCALES` 和 `PSTORE_SMOKE_FULL=1` 可扩大线上覆盖，用于检查 persisted query hash 或字段结构是否漂移。
+
+## 许可
+
+MIT

package/dist/api/batarang.d.ts

@@ -0,0 +1,25 @@
+import type { ConceptId, BatarangData, PsnLocale } from "../types.js";
+/**
+ * Fetch a PSN concept page HTML (raw) for concept ID extraction.
+ */
+export declare function fetchBatarangHtml(productId: string, locale?: PsnLocale): Promise<string | null>;
+/**
+ * Fetch a PSN concept page HTML and parse Batarang data.
+ */
+export declare function fetchBatarang(conceptId: ConceptId, locale?: PsnLocale): Promise<BatarangData | null>;
+/**
+ * Fetch a PSN product page HTML and parse Batarang data.
+ */
+export declare function fetchBatarangByProduct(productId: string, locale?: PsnLocale): Promise<BatarangData | null>;
+/**
+ * Extract concept ID from a product page HTML.
+ */
+export declare function extractConceptId(html: string): string | null;
+/**
+ * Extract all env script contents from HTML.
+ */
+export declare function extractEnvScripts(html: string): string[];
+/**
+ * Parse and merge all Batarang env scripts into a single data object.
+ */
+export declare function parseBatarangAll(html: string): BatarangData;

package/dist/api/browse.d.ts

@@ -0,0 +1,64 @@
+import type { PsnLocale } from "../types.js";
+import { type CategoryGridItem } from "./graphql.js";
+export declare const BROWSE_ALIAS: "browse";
+export declare const BROWSE_CLIENT_ID = "b6de8d4d-bf9b-11ee-ad2a-aea73dc1ea43";
+export declare const BROWSE_EXPERIENCE_ID = "7bbceafe-bfa8-11ee-b375-5e45f4e139ac";
+export declare const BROWSE_CATEGORY_ID = "28c9c2b2-cecc-415c-9a08-482a605cb104";
+export declare const BROWSE_LOCALIZED_KEY_ID = "cat.gma.x_All_games";
+export type BrowseWindow = "all" | "next-thirty-days" | "last-thirty-days";
+export type BrowseSort = string;
+export type BrowseOrder = "asc" | "desc";
+export interface BrowseQuery {
+    window?: string;
+    sortBy?: string;
+    order?: string;
+    page?: number;
+    size?: number;
+    locale?: PsnLocale;
+    sample?: number;
+    filters?: string[];
+    platforms?: string[];
+    genres?: string[];
+    prices?: string[];
+    classifications?: string[];
+    ageRatings?: string[];
+    vrCompatibilities?: string[];
+    notices?: string[];
+}
+export interface BrowseResolvedQuery {
+    window: BrowseWindow;
+    sortBy: BrowseSort;
+    order: BrowseOrder;
+    page: number;
+    size: number;
+    sample?: number;
+    filters: string[];
+}
+export interface BrowseGridResult {
+    categoryId: string;
+    items: CategoryGridItem[];
+    query: BrowseResolvedQuery;
+}
+/**
+ * Normalize the browse window string.
+ */
+export declare function normalizeBrowseWindow(input?: string): BrowseWindow;
+/**
+ * Resolve the browse sort defaults for a given window.
+ */
+export declare function resolveBrowseSortDefaults(window: BrowseWindow): {
+    sortBy: BrowseSort;
+    order: BrowseOrder;
+};
+/**
+ * Resolve a complete browse query from user input.
+ */
+export declare function resolveBrowseQuery(query: BrowseQuery): BrowseResolvedQuery;
+/**
+ * Randomly sample up to `count` items from a list.
+ */
+export declare function sampleItems<T>(items: T[], count: number, rng?: () => number): T[];
+/**
+ * Fetch browse results.
+ */
+export declare function fetchBrowseGrid(query: BrowseQuery): Promise<BrowseGridResult | null>;