@maixio/pstore 0.1.0

package/dist/locale.d.ts

@@ -0,0 +1,12 @@
+import type { PsnLocale, LocaleInfo } from "./types.js";
+export declare const DEFAULT_LOCALE: PsnLocale;
+export declare const TITLE_LOCALE_PRESETS: Record<string, PsnLocale[]>;
+export declare function isPsnLocale(value: string | undefined | null): value is PsnLocale;
+export declare function normalizeLocale(value: string | undefined | null): PsnLocale;
+export declare function getLocaleInfo(locale?: string | null): LocaleInfo;
+export declare function localeToSearchParams(locale?: string | null): {
+    countryCode: string;
+    languageCode: string;
+};
+export declare function localeToStorePath(locale?: string | null): string;
+export declare function parseLocaleList(input: string | undefined | null): PsnLocale[];

package/dist/log.d.ts

@@ -0,0 +1,31 @@
+export type LogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    module: string;
+    message: string;
+    data?: Record<string, unknown>;
+    durationMs?: number;
+}
+/**
+ * Write a log entry to file.
+ */
+export declare function log(level: LogLevel, module: string, message: string, data?: Record<string, unknown>, durationMs?: number): void;
+export declare const logger: {
+    debug: (module: string, msg: string, data?: Record<string, unknown>) => void;
+    info: (module: string, msg: string, data?: Record<string, unknown>, dur?: number) => void;
+    warn: (module: string, msg: string, data?: Record<string, unknown>) => void;
+    error: (module: string, msg: string, data?: Record<string, unknown>) => void;
+};
+/**
+ * Measure execution time of an async function and log it.
+ */
+export declare function timedLog<T>(module: string, operation: string, fn: () => Promise<T>, data?: Record<string, unknown>): Promise<T>;
+/**
+ * Get log files list with sizes.
+ */
+export declare function getLogFiles(): Array<{
+    name: string;
+    size: number;
+    date: Date;
+}>;

package/dist/perf.d.ts

@@ -0,0 +1,16 @@
+export declare class PerfTracer {
+    private readonly startTime;
+    private readonly spans;
+    private readonly label;
+    constructor(label?: string);
+    /** Measure the execution time of an async function. */
+    span<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /** Measure the execution time of a sync function. */
+    spanSync<T>(name: string, fn: () => T): T;
+    /** Get elapsed time in ms. */
+    elapsed(): number;
+    /** Get all span durations as a plain object. */
+    getTiming(): Record<string, number>;
+    /** Print time distribution table to console. */
+    report(): void;
+}

package/dist/provider.d.ts

@@ -0,0 +1,16 @@
+import type { LookupResult, LookupOptions } from "./types.js";
+export interface LookupResponse {
+    result: LookupResult | null;
+    fromCache: boolean;
+}
+/**
+ * Look up a game by concept ID or product ID.
+ *
+ * Auto-detects ID type (conceptId = numeric, productId = alphanumeric).
+ * Runs all API requests in parallel with graceful degradation.
+ */
+export declare function lookupGame(id: string, options?: LookupOptions): Promise<LookupResponse>;
+/**
+ * Clear all caches.
+ */
+export declare function clearCaches(): void;

package/dist/types.d.ts

@@ -0,0 +1,253 @@
+export type PsnLocale = "zh-hans-HK" | "zh-hant-HK" | "en-HK" | "zh-hant-TW" | "en-TW" | "ja-JP" | "en-US" | "en-GB" | "zh-hans-CN";
+export interface LocaleInfo {
+    locale: PsnLocale;
+    language: string;
+    country: string;
+    region: string;
+    currency: string;
+}
+export declare const LOCALE_MAP: Record<PsnLocale, LocaleInfo>;
+/** Concept ID (numeric string, e.g. "10014149") */
+export type ConceptId = string;
+/** Product ID (alphanumeric with dashes, e.g. "UP1001-PPSA28420_00-NBA2K26000000000") */
+export type ProductId = string;
+export interface Price {
+    basePrice: string | null;
+    basePriceValue: number | null;
+    discountedPrice: string | null;
+    discountedValue: number | null;
+    discountText: string | null;
+    currencyCode: string | null;
+    endTime: string | null;
+    /** True only when the product's own list price is zero. */
+    isFree?: boolean;
+    /** True when the current CTA is included through a subscription or entitlement. */
+    isIncluded?: boolean;
+    discountPercent?: number | null;
+}
+export interface Sku {
+    id: string;
+    name: string;
+    displayPrice?: string;
+    price?: number;
+    type?: string;
+}
+export interface RatingDistribution {
+    percentage: string;
+    percentageRaw: number;
+    rating: number;
+}
+export interface StarRating {
+    averageRating: number;
+    averageRatingForDisplay?: string;
+    ratingsDistribution?: RatingDistribution[];
+    totalRatingsCount?: number;
+}
+export type MediaRole = "PREVIEW" | "FOUR_BY_THREE_BANNER" | "GAMEHUB_COVER_ART" | "HERO_CHARACTER" | "LOGO" | "PORTRAIT_BANNER" | "SCREENSHOT" | "MASTER" | "BACKGROUND_LAYER_ART" | "BACKGROUND" | "EDITION_KEY_ART";
+export type MediaType = "IMAGE" | "VIDEO";
+export interface Media {
+    role: MediaRole;
+    type: MediaType;
+    url: string;
+}
+export type DescriptionType = "SHORT" | "LONG" | "COMPATIBILITY_NOTICE" | "LEGAL";
+export interface Description {
+    type: DescriptionType;
+    /** ⚠️ field is `value` NOT `text` */
+    value: string;
+}
+export interface Edition {
+    name: string;
+    type?: string;
+    features?: string[];
+}
+export interface Product {
+    id: ProductId;
+    name: string;
+    edition?: Edition | null;
+    price?: Price;
+    localizedGenres?: {
+        value: string;
+    }[];
+    platforms?: string[];
+    skus?: Sku[];
+    storeDisplayClassification?: string;
+    topCategory?: string;
+    npTitleId?: string;
+    media?: Media[];
+    starRating?: StarRating;
+    webctas?: GameCTA[];
+    contentRating?: ContentRating | null;
+    invariantName?: string;
+    isInWishlist?: boolean;
+    isWishlistable?: boolean;
+}
+export interface GameCTA {
+    type: string;
+    price?: Price;
+    action?: {
+        type: string;
+        param: {
+            name: string;
+            value: string;
+        }[];
+    };
+    meta?: {
+        preOrder: boolean;
+    };
+}
+export interface ContentRating {
+    name?: string;
+    descriptors?: {
+        name: string;
+        authority: string;
+    }[];
+}
+export interface BatarangData {
+    name?: string;
+    edition?: string;
+    genres?: string[];
+    platforms?: string[];
+    classification?: string;
+    topCategory?: string;
+    starRating?: StarRating;
+    npTitleId?: string;
+    descriptions?: Description[];
+    publisherName?: string;
+    compatibilityNoticesByPlatform?: Record<string, unknown>;
+    screenLanguages?: string[];
+    spokenLanguages?: string[];
+    releaseDate?: string;
+    contentRating?: ContentRating;
+}
+export interface LookupResult {
+    id: ConceptId | ProductId;
+    /** Input/result object type. Mirrors PSN's conceptRetrieve/productRetrieve boundary. */
+    idType?: "concept" | "product";
+    /** Owning concept ID when known. */
+    conceptId?: ConceptId;
+    /** Product ID when the primary result is a product, or the default product for a concept. */
+    productId?: ProductId;
+    name: string;
+    locale: PsnLocale;
+    /** Localized product name from Telemetry API */
+    productName?: string;
+    /** Edition name */
+    edition?: string;
+    /** Localized genres */
+    genres?: string[];
+    /** Publisher name (from Batarang) */
+    publisher?: string;
+    /** Release date */
+    releaseDate?: string;
+    /** Price info */
+    price?: Price;
+    /** Star rating */
+    starRating?: StarRating;
+    /** Store display classification */
+    classification?: string;
+    /** Top category */
+    topCategory?: string;
+    /** Platform list */
+    platforms?: string[];
+    /** SKUs */
+    skus?: Sku[];
+    /** Description texts */
+    descriptions?: Description[];
+    /** Media resources */
+    media?: Media[];
+    /** Related product editions */
+    products?: Product[];
+    /** npTitleId */
+    npTitleId?: string;
+    /** Content rating */
+    contentRating?: ContentRating;
+    /** Source provenance for key fields */
+    sources?: LookupSources;
+    /** Performance timing info */
+    timing?: Record<string, number>;
+    /** Non-fatal source failures captured during lookup. */
+    warnings?: LookupWarning[];
+    /** Localized titles keyed by PSN locale. */
+    localizedTitles?: Partial<Record<PsnLocale, string>>;
+    /** Optional concept/default-product data for product lookups. */
+    concept?: LookupResult;
+}
+export interface LookupWarning {
+    source: "telemetry" | "price" | "rating" | "upsell" | "batarang" | "resolveConcept";
+    message: string;
+}
+export type LookupSource = "telemetry" | "rating" | "batarang" | "price" | "upsell" | "derived" | "none";
+export interface LookupSources {
+    name: LookupSource;
+    edition: LookupSource;
+    genres: LookupSource;
+    publisher: LookupSource;
+    releaseDate: LookupSource;
+    price: LookupSource;
+    starRating: LookupSource;
+    classification: LookupSource;
+    topCategory: LookupSource;
+    platforms: LookupSource;
+    skus: LookupSource;
+    descriptions: LookupSource;
+    media: LookupSource;
+    products: LookupSource;
+    npTitleId: LookupSource;
+    contentRating: LookupSource;
+}
+export interface SearchResultItem {
+    id: string;
+    name: string;
+    type: "concept" | "product";
+    price?: string;
+    platforms?: string[];
+    classification?: string;
+}
+export interface SearchResults {
+    items: SearchResultItem[];
+    total?: number;
+    page: number;
+    size: number;
+    locale: PsnLocale;
+}
+export interface CategoryResults {
+    items: SearchResultItem[];
+    total: number;
+    page: number;
+    size: number;
+    catalogId: string;
+    catalogName?: string;
+    locale: PsnLocale;
+}
+export interface CategoryGridParams {
+    id: string;
+    pageArgs: {
+        offset: number;
+        size: number;
+    };
+    sortBy?: string | null;
+    filterBy?: string[];
+    facetOptions?: string[];
+    maxResults?: number | null;
+}
+export { CATALOG_ALIASES } from "./api/catalog-registry.js";
+export interface LookupOptions {
+    locale?: PsnLocale;
+    profile?: "default" | "title-maintenance";
+    includeTelemetry?: boolean;
+    includePrice?: boolean;
+    includeRating?: boolean;
+    includeUpsell?: boolean;
+    includeProducts?: boolean;
+    includeConcept?: boolean;
+    includeBatarang?: boolean;
+    fields?: string[];
+    titleLocales?: PsnLocale[];
+}
+export declare class PsnApiError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly operationName?: string | undefined;
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined, operationName?: string | undefined, retryAfterMs?: number | undefined);
+}

package/dist/utils.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Extract concept ID from a string (numeric ID like "10014149").
+ * Returns null if the string looks like a product ID.
+ */
+export declare function detectIdType(id: string): "concept" | "product";
+/**
+ * Format price value (in cents) to display string.
+ * e.g. (54800, "HKD") → "HK$548.00"
+ */
+export declare function formatPrice(value: number | null, currency?: string | null): string;
+/**
+ * Format price value for display (no currency symbol).
+ */
+export declare function formatPriceValue(value: number | null, decimals?: number): string;
+/**
+ * Calculate discount percentage.
+ * e.g. (78900, 31560) → 60
+ */
+export declare function calcDiscountPercent(listPrice: number, salePrice: number): number | null;
+/**
+ * True when the product's own list price is zero. Subscription-included paid
+ * products often report discountedValue=0 and must not be treated as free.
+ */
+export declare function isFreePrice(basePriceValue?: number | null, discountedValue?: number | null): boolean;
+/**
+ * True when the current CTA is an entitlement/subscription inclusion rather
+ * than a normal zero-price product.
+ */
+export declare function isIncludedPrice(basePriceValue?: number | null, discountedValue?: number | null, discountText?: string | null, discountedPrice?: string | null): boolean;
+/**
+ * Strip language tags from product name.
+ * e.g. "PS5®版《NBA 2K26》 (日语, 韩语, 简体中文...)" → "PS5®版《NBA 2K26》"
+ */
+export declare function stripLanguageTags(name: string): string;
+/**
+ * Classify product type based on name.
+ */
+export declare function classifyProductType(name: string): "edition" | "dlc" | "addon" | "currency" | "unknown";
+/**
+ * Decode HTML entities in a string.
+ */
+export declare function htmlEntityDecode(str: string): string;
+/**
+ * Strip HTML tags from a string.
+ */
+export declare function stripHtml(html: string): string;
+/**
+ * Truncate text for display.
+ */
+export declare function truncate(text: string | null | undefined, maxLen: number): string;
+/**
+ * Format a Date-like string to a readable display format.
+ */
+export declare function formatDate(dateStr?: string | null): string;

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@maixio/pstore",
+  "version": "0.1.0",
+  "description": "Unofficial PlayStation Store CLI and SDK for querying publicly available game metadata",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "pstore": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.3.0"
+  },
+  "packageManager": "bun@1.3.11",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maixiang-sh/pstore.git"
+  },
+  "keywords": [
+    "playstation",
+    "playstation-store",
+    "psn",
+    "cli",
+    "game",
+    "catalog"
+  ],
+  "scripts": {
+    "build": "bun run clean && bun run build:index && bun run build:cli && bun run build:types",
+    "clean": "rm -rf dist",
+    "build:index": "bun build src/index.ts --target=node --format=esm --outdir=dist",
+    "build:cli": "bun build src/cli.ts --target=node --format=esm --outdir=dist",
+    "build:types": "tsc -p tsconfig.types.json && bun run scripts/fix-dts-extensions.ts",
+    "prepack": "bun run build",
+    "prepublishOnly": "bun test && bun run typecheck && bun run build && bun pm pack --dry-run",
+    "lint": "biome lint src",
+    "format": "biome format --write src README.md README.zh-CN.md",
+    "lookup": "bun run src/cli.ts lookup",
+    "search": "bun run src/cli.ts search",
+    "category": "bun run src/cli.ts category",
+    "browse": "bun run src/cli.ts browse",
+    "live-smoke": "bun run src/live-smoke.ts",
+    "test:live": "bun run src/live-smoke.ts",
+    "test:live:full": "PSTORE_SMOKE_FULL=1 bun run src/live-smoke.ts",
+    "test:live:locales": "PSTORE_SMOKE_LOCALES=zh-hans-HK,en-US,ja-JP,zh-hant-TW,en-TW bun run src/live-smoke.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}