@retropak/types 1.0.0-draft

package/README.md

@@ -0,0 +1,33 @@
+# @retropak/types
+
+TypeScript type definitions for Retropak manifests, automatically generated from the JSON Schema.
+
+## Installation
+
+```bash
+npm install @retropak/types
+```
+
+## Usage
+
+```typescript
+import type { RetropakManifest } from '@retropak/types';
+
+const manifest: RetropakManifest = {
+  // Your manifest data with full type safety
+};
+```
+
+## Development
+
+This package is part of the Retropak monorepo. Types are automatically generated from the JSON Schema.
+
+To regenerate types after schema changes:
+
+```bash
+npm run build
+```
+
+## License
+
+CC0-1.0

package/dist/generated.d.ts

@@ -0,0 +1,497 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+/**
+ * A classification for the type/nature of the software.
+ */
+export type Category = "addon" | "application" | "beta" | "bios" | "compilation" | "coverdisk" | "demo" | "educational" | "firmware" | "freeware" | "game" | "homebrew" | "multimedia" | "promotional" | "prototype" | "scene_demo" | "shareware" | "unlicensed" | "utility";
+/**
+ * Genre classification.
+ */
+export type Genre = "action_rpg" | "action" | "adventure" | "american_football" | "arcade" | "artillery" | "athletics" | "baseball" | "basketball" | "beat_em_up" | "billiards" | "block_puzzle" | "board_game" | "bowling" | "boxing" | "bullet_hell" | "card_game" | "casino" | "casual" | "cricket" | "cute_em_up" | "dating_sim" | "dungeon_crawler" | "educational" | "endless_runner" | "extreme_sports" | "fighting" | "fishing" | "flight" | "fps" | "golf" | "hack_and_slash" | "hockey" | "horror" | "horse_racing" | "life_sim" | "light_gun" | "logic_puzzle" | "mahjong" | "management" | "match_3" | "maze" | "mech" | "metroidvania" | "minigames" | "mmorpg" | "moba" | "music_rhythm" | "open_world" | "pachinko" | "party" | "pinball" | "platformer" | "point_and_click" | "pool" | "puzzle" | "quiz" | "racing" | "rail_shooter" | "real_time_strategy" | "roguelike" | "rpg" | "run_and_gun" | "sandbox" | "shoot_em_up" | "shooter" | "simulation" | "skateboarding" | "skiing" | "snooker" | "snowboarding" | "soccer" | "sports" | "stealth" | "strategy" | "surfing" | "survival" | "tactical_rpg" | "tennis" | "text_adventure" | "tower_defense" | "trivia" | "turn_based_strategy" | "twin_stick" | "vehicle_combat" | "visual_novel" | "volleyball" | "word_puzzle" | "wrestling";
+/**
+ * Input device, peripheral, or capability.
+ */
+export type Feature = "analog_stick" | "arcade_stick" | "balance_board" | "bongos" | "buzzer" | "camera" | "crank" | "dance_mat" | "dongle" | "drums" | "fishing_rod" | "flight_stick" | "gamepad" | "guitar" | "instrument" | "keyboard_controller" | "keyboard" | "light_gun" | "link_cable" | "maracas" | "mech_controller" | "microphone" | "motion_controls" | "mouse" | "multitap" | "nfc_portal" | "online" | "paddle" | "pedals" | "pointer" | "rumble" | "save_file" | "spinner" | "steering_wheel" | "stylus" | "touch_screen" | "trackball" | "train_controller" | "turntable" | "twin_stick" | "vr_headset" | "zapper";
+/**
+ * Name of a title included in a compilation release.
+ */
+export type CompilationTitle = string;
+/**
+ * The format/medium type of the file.
+ */
+export type MediaType = "archive" | "bluray" | "cartridge" | "cdrom" | "download" | "dvd" | "floppy" | "gd_rom" | "hdd_image" | "laserdisc" | "memory_card" | "tape" | "umd";
+/**
+ * Region encoding.
+ */
+export type Region = "asia" | "australia" | "brazil" | "canada" | "china" | "europe" | "france" | "germany" | "hong-kong" | "india" | "italy" | "japan" | "korea" | "mexico" | "netherlands" | "ntsc-j" | "ntsc-u" | "pal-a" | "pal-b" | "pal-g" | "pal" | "russia" | "scandinavia" | "spain" | "taiwan" | "uk" | "usa" | "world";
+/**
+ * Quality/status of the ROM dump.
+ */
+export type DumpStatus = "alternate" | "bad" | "good" | "hacked" | "overdump" | "pirate" | "prototype" | "trained" | "translated" | "underdump" | "unknown" | "unlicensed";
+/**
+ * Metadata specification for Retropak software containers
+ */
+export interface RetropakManifest {
+    /**
+     * The schema version this manifest conforms to, using schemaver format MODEL-REVISION-ADDITION (e.g., '1-0-0').
+     */
+    schemaVersion: string;
+    /**
+     * Version of this manifest file, for tracking revisions (e.g., '1', '2.1').
+     */
+    manifestVersion?: string;
+    /**
+     * Title metadata and information.
+     */
+    info: {
+        /**
+         * The primary display name of the title.
+         */
+        title: string;
+        /**
+         * Alternative names (e.g. regional titles, translated names).
+         */
+        alternativeTitles?: string[];
+        /**
+         * Unique identifier for the platform.
+         */
+        platform: "32x" | "3do" | "3ds" | "a2600" | "a5200" | "a7800" | "a800" | "amiga" | "apple2" | "aquarius" | "archimedes" | "arduboy" | "astrocade" | "bbc" | "c128" | "c64" | "cd32" | "cdi" | "cdtv" | "channelf" | "coco" | "coleco" | "cpc" | "dos" | "dragon" | "dreamcast" | "einstein" | "electron" | "emerson" | "enterprise" | "fds" | "fmtowns" | "gamecom" | "gamecube" | "gamewave" | "gamate" | "gb" | "gba" | "gbc" | "gg" | "gizmondo" | "gnw" | "gp2x" | "gp32" | "gx4000" | "hyperscan" | "intellivision" | "jaguar" | "jaguarcd" | "laseractive" | "lynx" | "markiii" | "mcd" | "md" | "megaduck" | "microvision" | "mp1000" | "msx" | "msx2" | "n64" | "nds" | "nes" | "ng" | "ngage" | "ngcd" | "ngp" | "ngpc" | "nuon" | "o2" | "oric" | "pc88" | "pc98" | "pce" | "pcecd" | "pcfx" | "pet" | "pico" | "pippin" | "playdate" | "plus4" | "pokemini" | "ps2" | "ps3" | "ps4" | "ps5" | "psp" | "psx" | "pv1000" | "ql" | "sam" | "saturn" | "scv" | "sg1000" | "sgx" | "sms" | "snes" | "spectrum" | "st" | "studio2" | "supervision" | "switch" | "thomson" | "ti994a" | "tigerhandheld" | "trs80" | "tutor" | "vb" | "vcg" | "vectrex" | "vic20" | "videopac" | "vita" | "wii" | "wiiu" | "ws" | "wsc" | "x360" | "x68000" | "xavix" | "xbox" | "xone" | "xsx" | "zeebo" | "zx80" | "zx81";
+        /**
+         * The studio or individual who developed the title.
+         */
+        developer?: string;
+        /**
+         * The company that published the title.
+         */
+        publisher?: string;
+        /**
+         * Country of origin where the title was developed (ISO 3166-1 alpha-2 code, e.g. 'jp', 'us', 'gb').
+         */
+        country?: string;
+        /**
+         * Original release date in ISO 8601 format (YYYY-MM-DD).
+         */
+        releaseDate?: string;
+        /**
+         * A text summary or synopsis of the title.
+         */
+        description?: string;
+        /**
+         * One or more classifications for the type/nature of the software.
+         */
+        category?: Category[];
+        /**
+         * One or more genre classifications.
+         */
+        genre?: Genre[];
+        players?: Players;
+        features?: Features;
+        /**
+         * Languages supported (ISO 639-1 codes, e.g. 'en', 'ja', 'de').
+         */
+        languages?: string[];
+        /**
+         * People who worked on the title.
+         */
+        credits?: CreditEntry[];
+        /**
+         * For compilations: list of titles included in this release. Include "compilation" in the category array when using this field.
+         */
+        contents?: CompilationTitle[];
+        /**
+         * Identifiers from external databases for cross-referencing.
+         */
+        externalIds?: {
+            /**
+             * IGDB (Internet Game Database) ID.
+             */
+            igdb?: number;
+            /**
+             * MobyGames ID.
+             */
+            mobygames?: number;
+            /**
+             * TheGamesDB ID.
+             */
+            thegamesdb?: number;
+            /**
+             * ScreenScraper ID.
+             */
+            screenscraper?: number;
+            /**
+             * RAWG ID.
+             */
+            rawg?: number;
+            /**
+             * GameFAQs ID.
+             */
+            gamefaqs?: number;
+            [k: string]: unknown;
+        };
+        rating?: AgeRating;
+        /**
+         * Additional notes, warnings, or information (e.g. access codes, compatibility notes, copy protection details).
+         */
+        notes?: string;
+        [k: string]: unknown;
+    };
+    /**
+     * The media files (ROMs, disc images, tapes, etc.) included in this package.
+     *
+     * @minItems 1
+     */
+    media: [MediaItem, ...MediaItem[]];
+    /**
+     * Artwork, documentation, and other supplementary files.
+     */
+    assets?: {
+        boxFront?: Image;
+        boxBack?: Image1;
+        boxSpine?: Image2;
+        /**
+         * Images of the physical media (cartridge, disc, tape, floppy, etc.).
+         */
+        physicalMedia?: PhysicalMediaImage[];
+        logo?: Image3;
+        backdrop?: Image4;
+        titleScreen?: Image5;
+        /**
+         * Gameplay screenshots.
+         */
+        gameplay?: Image6[];
+        /**
+         * Path to the manual (PDF, image, html or text).
+         */
+        manual?: string;
+        map?: Image7;
+        /**
+         * Soundtrack or audio files from the game.
+         */
+        music?: MusicTrack[];
+        [k: string]: unknown;
+    };
+    /**
+     * External configuration files for emulators or platforms.
+     */
+    config?: ConfigFile[];
+    [k: string]: unknown;
+}
+/**
+ * Multiplayer capabilities.
+ */
+export interface Players {
+    /**
+     * Minimum number of players required to play.
+     */
+    min?: number;
+    /**
+     * Maximum number of simultaneous players supported.
+     */
+    max?: number;
+    /**
+     * Whether cooperative play is supported.
+     */
+    coop?: boolean;
+    [k: string]: unknown;
+}
+/**
+ * Input devices, peripherals, and capabilities.
+ */
+export interface Features {
+    /**
+     * Features required to use this title.
+     */
+    required?: Feature[];
+    /**
+     * Optional features the title supports.
+     */
+    supported?: Feature[];
+    [k: string]: unknown;
+}
+/**
+ * A person credited for work on the title.
+ */
+export interface CreditEntry {
+    /**
+     * Person's name.
+     */
+    name: string;
+    /**
+     * Job titles or roles (e.g. 'Director', 'Lead Programmer', 'Composer').
+     */
+    roles?: string[];
+    [k: string]: unknown;
+}
+/**
+ * Age/content ratings from various rating boards.
+ */
+export interface AgeRating {
+    /**
+     * Whether the title contains adult or explicit content.
+     */
+    nsfw?: boolean;
+    /**
+     * Generic minimum recommended age when no official rating exists.
+     */
+    minimum?: number;
+    /**
+     * ESRB rating (North America).
+     */
+    esrb?: "ec" | "e" | "e10" | "t" | "m" | "ao" | "rp";
+    /**
+     * PEGI rating (Europe).
+     */
+    pegi?: "3" | "7" | "12" | "16" | "18";
+    /**
+     * CERO rating (Japan).
+     */
+    cero?: "a" | "b" | "c" | "d" | "z";
+    /**
+     * USK rating (Germany).
+     */
+    usk?: "0" | "6" | "12" | "16" | "18";
+    /**
+     * ACB rating (Australia).
+     */
+    acb?: "g" | "pg" | "m" | "ma15" | "r18" | "rc";
+    /**
+     * GRAC rating (South Korea).
+     */
+    grac?: "all" | "12" | "15" | "18";
+    /**
+     * BBFC rating (United Kingdom).
+     */
+    bbfc?: "u" | "pg" | "12" | "12a" | "15" | "18" | "r18";
+    [k: string]: unknown;
+}
+/**
+ * A media file (ROM, disc image, tape, etc.).
+ */
+export interface MediaItem {
+    /**
+     * Unique identifier for this media item, used for referencing in other fields.
+     */
+    id?: string;
+    /**
+     * Relative path to the media file within the archive.
+     */
+    filename: string;
+    /**
+     * Display name for this specific media item (e.g. 'Disc 1').
+     */
+    label?: string;
+    type: MediaType;
+    /**
+     * Whether the title can be started from this media. Set to false for data-only discs.
+     */
+    bootable?: boolean;
+    /**
+     * Sequence number for multi-part media.
+     */
+    index?: number;
+    region?: Region;
+    /**
+     * MD5 checksum of the media file for verification.
+     */
+    md5?: string;
+    /**
+     * SHA-1 checksum of the media file for verification.
+     */
+    sha1?: string;
+    /**
+     * CRC32 checksum of the media file for verification.
+     */
+    crc32?: string;
+    /**
+     * Version identifier for this ROM/media (e.g. 'Rev A', '1.1', 'v1.0').
+     */
+    version?: string;
+    status?: DumpStatus;
+    /**
+     * Whether this dump has been verified against a known database (No-Intro, Redump, etc.).
+     */
+    verified?: boolean;
+    /**
+     * Source database or group that verified the dump (e.g. 'No-Intro', 'Redump', 'TOSEC').
+     */
+    source?: string;
+    /**
+     * Official product serial/catalog number from the original media.
+     */
+    serial?: string;
+    /**
+     * Additional notes about this specific media file (e.g. distribution method, requirements, known issues).
+     */
+    notes?: string;
+    [k: string]: unknown;
+}
+/**
+ * Front box/case cover image.
+ */
+export interface Image {
+    /**
+     * Path to the image file.
+     */
+    file: string;
+    /**
+     * Alternative text describing the image for accessibility.
+     */
+    alt?: string;
+    [k: string]: unknown;
+}
+/**
+ * Back box/case cover image.
+ */
+export interface Image1 {
+    /**
+     * Path to the image file.
+     */
+    file: string;
+    /**
+     * Alternative text describing the image for accessibility.
+     */
+    alt?: string;
+    [k: string]: unknown;
+}
+/**
+ * Box/case spine image.
+ */
+export interface Image2 {
+    /**
+     * Path to the image file.
+     */
+    file: string;
+    /**
+     * Alternative text describing the image for accessibility.
+     */
+    alt?: string;
+    [k: string]: unknown;
+}
+/**
+ * An image of physical media (cartridge, disc, tape, etc.).
+ */
+export interface PhysicalMediaImage {
+    /**
+     * Path to the physical media image file.
+     */
+    file: string;
+    /**
+     * Alternative text describing the image for accessibility.
+     */
+    alt?: string;
+    /**
+     * References the 'id' field of a media item, if specific to one disc/cart.
+     */
+    mediaId?: string;
+    type?: MediaType;
+    [k: string]: unknown;
+}
+/**
+ * Logo/wordmark with transparent background.
+ */
+export interface Image3 {
+    /**
+     * Path to the image file.
+     */
+    file: string;
+    /**
+     * Alternative text describing the image for accessibility.
+     */
+    alt?: string;
+    [k: string]: unknown;
+}
+/**
+ * Widescreen background artwork for TV/big screen interfaces. Should be free of text or logos.
+ */
+export interface Image4 {
+    /**
+     * Path to the image file.
+     */
+    file: string;
+    /**
+     * Alternative text describing the image for accessibility.
+     */
+    alt?: string;
+    [k: string]: unknown;
+}
+/**
+ * Title screen screenshot.
+ */
+export interface Image5 {
+    /**
+     * Path to the image file.
+     */
+    file: string;
+    /**
+     * Alternative text describing the image for accessibility.
+     */
+    alt?: string;
+    [k: string]: unknown;
+}
+/**
+ * An image file with optional alt text for accessibility.
+ */
+export interface Image6 {
+    /**
+     * Path to the image file.
+     */
+    file: string;
+    /**
+     * Alternative text describing the image for accessibility.
+     */
+    alt?: string;
+    [k: string]: unknown;
+}
+/**
+ * An image file with optional alt text for accessibility.
+ */
+export interface Image7 {
+    /**
+     * Path to the image file.
+     */
+    file: string;
+    /**
+     * Alternative text describing the image for accessibility.
+     */
+    alt?: string;
+    [k: string]: unknown;
+}
+/**
+ * A soundtrack or audio file from the title.
+ */
+export interface MusicTrack {
+    /**
+     * Display name of the music track.
+     */
+    title?: string;
+    /**
+     * Path to the audio file.
+     */
+    file: string;
+    /**
+     * Whether this track is suitable for background/menu music when browsing titles.
+     */
+    background?: boolean;
+    [k: string]: unknown;
+}
+/**
+ * An external configuration file for emulator or platform-specific settings.
+ */
+export interface ConfigFile {
+    /**
+     * Path to the configuration file.
+     */
+    file: string;
+    /**
+     * Target emulator, core, or platform (e.g. 'retroarch', 'mame', 'dolphin').
+     */
+    target?: string;
+    /**
+     * What this config file does or overrides.
+     */
+    description?: string;
+    [k: string]: unknown;
+}

package/dist/generated.js

@@ -0,0 +1,7 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export all generated types from the schema
+ */
+export * from "./generated";

package/dist/index.js

@@ -0,0 +1,5 @@
+/* eslint-disable */
+/**
+ * Re-export all generated types from the schema
+ */
+export * from "./generated";

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@retropak/types",
+    "version": "1.0.0-draft",
+    "description": "TypeScript type definitions for Retropak manifests",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src"
+    ],
+    "scripts": {
+        "prebuild": "rm -rf dist",
+        "build": "npm run generate && tsc",
+        "generate": "json2ts -i ../schema/schemas/v1/retropak.schema.json -o src/generated.ts",
+        "validate": "tsc --noEmit",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "retropak",
+        "types",
+        "typescript"
+    ],
+    "author": "piers@retropak.org",
+    "license": "CC0-1.0",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/piersroberts/retropak.git",
+        "directory": "packages/types"
+    },
+    "bugs": {
+        "url": "https://github.com/piersroberts/retropak/issues"
+    },
+    "homepage": "https://retropak.org",
+    "dependencies": {
+        "@retropak/schema": "*"
+    },
+    "devDependencies": {
+        "json-schema-to-typescript": "^13.1.2",
+        "typescript": "^5.3.3"
+    },
+    "peerDependencies": {
+        "typescript": ">=4.5.0"
+    }
+}