@simeonradivoev/gameflow-sdk 1.5.1 → 1.6.0

package/README.md

@@ -13,3 +13,18 @@ The package must expose a main script gameflow will import and validate. It must
 
 For the plugin to show up in the UI for download. It must be published to NPM with the `gameflow-plugin` keyword. Gameflow uses bun to install plugins as packages from npmjs.
 Follow publishing instruction check the [NPM Docs](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
+
+## Dependencies
+
+Peer dependencies will not be installed when the run adds the plugin package. They are provided by gameflow.
+All peer dependencies can be marked as external as gameflow provides it. There is a helper build script that does all that for you, to run it use.
+
+`bunx gameflow-build --entry=index.ts`
+
+supported arguments are
+`--entry` the entry of the app to build
+`--outdir` Where to build. Default is 'dist'
+`--minify` Minify the code. Default is 'false'
+`--sourcemap` Include a source map. Default is 'none'
+
+If you want to include dependencies that gameflow does not provide you have to bundle them in. Gameflow does not load dependencies for you.

package/build.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env bun
+
+import pkg from './package.json';
+
+import { parseArgs } from "util";
+
+const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+        outdir: { type: "string", default: "dist" },
+        minify: { type: "boolean", default: false },
+        sourcemap: { type: "string", default: "none" },  // "none" | "inline" | "external"
+        entry: { type: "string", default: "src/index.ts" },
+    },
+    allowPositionals: true,
+});
+
+await Bun.build({
+    entrypoints: [values.entry],
+    outdir: values.outdir,
+    minify: values.minify,
+    sourcemap: values.sourcemap as any,
+    external: [...Object.keys(pkg.peerDependencies), pkg.name],
+    target: "bun",
+});
+
+console.log(`✅ Built to ${values.outdir}`);

package/hooks/app.ts

@@ -0,0 +1,12 @@
+import AuthHooks from "./auth";
+import EmulatorHooks from "./emulators";
+import GameHooks from "./games";
+import StoreHooks from "./store";
+
+export class GameflowHooks
+{
+    games = new GameHooks();
+    emulators = new EmulatorHooks();
+    auth = new AuthHooks();
+    store = new StoreHooks();
+}

package/hooks/auth.ts

@@ -0,0 +1,10 @@
+
+import { AsyncSeriesHook } from "tapable";
+import { DownloadFileEntry } from "../shared";
+
+export default class AuthHooks
+{
+    loginComplete = new AsyncSeriesHook<[ctx: {
+        service: string;
+    }], { auth?: string, files: DownloadFileEntry[]; } | undefined>(['ctx']);
+}

package/hooks/emulators.ts

@@ -0,0 +1,39 @@
+
+import { EmulatorPostInstallContextType } from "../index";
+import { DownloadFileEntry, EmulatorSourceEntryType, EmulatorSystem } from "../shared";
+import { AsyncSeriesBailHook, AsyncSeriesHook } from "tapable";
+
+export default class EmulatorHooks
+{
+    fetchBiosDownload = new AsyncSeriesBailHook<[ctx: {
+        emulator: string;
+        systems: EmulatorSystem[];
+        biosFolder: string;
+    }], { auth?: string, files: DownloadFileEntry[]; } | undefined>(['ctx']);
+
+    /** 
+     * Triggered when emulator is downloaded or updated
+     */
+    emulatorPostInstall = new AsyncSeriesHook<[ctx: EmulatorPostInstallContextType], { emulator: string; }>(['ctx']);
+    findEmulatorSource = new AsyncSeriesHook<[ctx: { emulator: string; sources: EmulatorSourceEntryType[]; }]>(['ctx']);
+    findEmulatorForSystem = new AsyncSeriesHook<[ctx: { system: string; emulators: string[]; }]>(['ctx']);
+
+    constructor()
+    {
+        this.emulatorPostInstall.intercept({
+            register (tap)
+            {
+                return {
+                    ...tap,
+                    fn: async (ctx: EmulatorPostInstallContextType, ...rest: any[]) =>
+                    {
+                        if (ctx.emulator === tap.emulator)
+                        {
+                            tap.fn(ctx, ...rest);
+                        }
+                    }
+                };
+            },
+        });
+    }
+}

package/hooks/games.ts

@@ -0,0 +1,174 @@
+
+import { EmulatorPackageType, GameListFilterType, CommandEntry, DownloadInfo, EmulatorSourceEntryType, EmulatorSupport, EmulatorSystem, FrontEndCollection, FrontEndFilterSets, FrontEndGameType, FrontEndGameTypeDetailed, FrontEndGameTypeWithIds, FrontEndId, FrontEndPlatformType, GameLookup, SaveFileChange, SaveSlots } from '../shared';
+import { SyncBailHook, AsyncSeriesHook, AsyncSeriesBailHook, AsyncSeriesWaterfallHook } from 'tapable';
+
+export default class GameHooks
+{
+    buildLaunchCommands = new AsyncSeriesBailHook<[ctx: {
+        source: string | null;
+        sourceId: string | null;
+        id: FrontEndId;
+        systemSlug: string;
+        gamePath: string | null,
+        mainGlob?: string | null,
+    }], CommandEntry[] | Error | undefined>(['ctx']);
+    /** override the launch command for an emulator
+         * @param ctx.autoValidCommands The auto generated command for example based on the ES-DE listing
+         * @param ctx.emulator The emulator ID if any
+         * @param ctx.game.source The source of the game
+         * @param ctx.game.sourceId The ID of the source. This could be for example the ROMM ID the game was
+         * @returns The argument list to be used when running the emulator. 
+         * If no emulator bin in the command entry is found the actual command will be used as the bin. 
+         */
+    emulatorLaunch = new AsyncSeriesBailHook<[ctx: {
+        autoValidCommand: CommandEntry;
+        dryRun: boolean,
+        game: {
+            source?: string;
+            sourceId?: string;
+            id: FrontEndId;
+            platformSlug?: string;
+        };
+    }], { args: string[], savesPath?: SaveSlots; env?: Record<string, string>; } | undefined, { emulator: string; }>(['ctx']);
+    /**
+     * Is the given emulator for the given command supported 
+     * @returns The current support level. Partial means it can affect some functionality. Full means fully integrated for example with portable ones where you can control all aspects.
+     * 
+    */
+    emulatorLaunchSupport = new SyncBailHook<[ctx: {
+        emulator: string;
+        source?: EmulatorSourceEntryType;
+    }], EmulatorSupport | undefined, { emulator: string; }>(['ctx']);
+    /** 
+     * Fetches and returns a list of games converted to frontend.
+     * @param ctx.localGameIds This is local game ids in the format '<source>@<sourceId>'
+     */
+    fetchGames = new AsyncSeriesHook<[ctx: {
+        query: GameListFilterType;
+        games: FrontEndGameTypeWithIds[];
+    }]>(['ctx']);
+    fetchFilters = new AsyncSeriesHook<[ctx: {
+        source?: string;
+        filters: FrontEndFilterSets;
+    }]>(['ctx']);
+    fetchGame = new AsyncSeriesBailHook<[ctx: {
+        source: string;
+        localGame?: FrontEndGameTypeDetailed;
+        id: string;
+    }], FrontEndGameTypeDetailed | undefined>(['ctx']);
+    searchGame = new AsyncSeriesBailHook<[ctx: {
+        source: string;
+        igdb_id?: number;
+        ra_id?: number;
+    }], FrontEndGameTypeDetailed | undefined>(['ctx']);
+    /** Get download file URLs
+     * @param ctx.checksum Check if file already exists using checksums
+     */
+    fetchDownloads = new AsyncSeriesBailHook<[ctx: {
+        source: string;
+        id: string;
+        downloadId?: string;
+    }], DownloadInfo[] | undefined>(['ctx']);
+    fetchRomFiles = new AsyncSeriesBailHook<[ctx: {
+        source: string;
+        id: string;
+    }], string[] | undefined>(['ctx']);
+    fetchRecommendedGamesForGame = new AsyncSeriesHook<[ctx: {
+        game: FrontEndGameTypeDetailed,
+        games: (FrontEndGameType & { metadata?: any; })[];
+    }]>(['ctx']);
+    fetchRecommendedGamesForEmulator = new AsyncSeriesHook<[cts: {
+        emulator: EmulatorPackageType;
+        systems: EmulatorSystem[];
+        games: FrontEndGameType[];
+    }]>(['ctx']);
+    fetchPlatform = new AsyncSeriesBailHook<[ctx: {
+        source: string;
+        id: string;
+    }], FrontEndPlatformType | undefined>(['ctx']);
+    platformLookup = new AsyncSeriesBailHook<[ctx: {
+        source?: string;
+        id?: string;
+        slug?: string;
+    }], {
+        slug: string;
+        url_logo?: string | null;
+        name?: string;
+        family_name?: string;
+    } | undefined>(['ctx']);
+    gameLookup = new AsyncSeriesWaterfallHook<[matches: Map<string, GameLookup[]>, ctx: {
+        source?: string,
+        id?: string;
+        search?: string;
+    }]>(['matches', 'ctx']);
+    fetchPlatforms = new AsyncSeriesHook<[ctx: {
+        platforms: FrontEndPlatformType[];
+    }]>(['ctx']);
+    prePlay = new AsyncSeriesHook<[ctx: {
+        source: string,
+        id: string;
+        saveFolderSlots: Record<string, { cwd: string; }>;
+        setProgress: (progress: number, state: string) => void,
+        command: CommandEntry;
+        gameInfo: {
+            platformSlug?: string;
+        };
+    }]>(["ctx"]);
+    /** 
+     * @param changedSaveFiles Auto detected changed files. This is mainly used to see what changed during gameplay
+     * @param validChangedSaveFiles This will be final valid changes to be saved using save integrations like rclone
+     */
+    postPlay = new AsyncSeriesHook<[ctx: {
+        source: string,
+        id: string;
+        saveFolderSlots?: SaveSlots;
+        changedSaveFiles: { subPath: string, cwd: string; }[],
+        validChangedSaveFiles: Record<string, SaveFileChange>,
+        command: CommandEntry;
+        gameInfo: {
+            platformSlug?: string;
+        };
+    }]>(["ctx"]);
+    postInstall = new AsyncSeriesHook<[ctx: {
+        source: string,
+        id: string;
+        files: string[];
+        info: DownloadInfo;
+    }]>(['ctx']);
+    fetchCollections = new AsyncSeriesHook<[ctx: { collections: FrontEndCollection[]; }]>(['ctx']);
+    fetchCollection = new AsyncSeriesBailHook<[ctx: { source: string, id: string; }], FrontEndCollection | undefined>(['ctx']);
+
+    constructor()
+    {
+        this.emulatorLaunchSupport.intercept({
+            register (tap)
+            {
+                return {
+                    ...tap,
+                    fn: (e: any, ...rest: any[]) =>
+                    {
+                        if (e.emulator === tap.emulator)
+                        {
+                            return tap.fn(e, ...rest);
+                        }
+                    }
+                };
+            },
+        });
+        this.emulatorLaunch.intercept({
+            register (tap)
+            {
+                return {
+                    ...tap,
+                    fn: async (e: any, ...rest: any[]) =>
+                    {
+                        if ((e.autoValidCommand as CommandEntry).emulator === tap.emulator)
+                        {
+                            return tap.fn(e, ...rest);
+                        }
+                    }
+                };
+            },
+        });
+    }
+}

package/hooks/store.ts

@@ -0,0 +1,10 @@
+import { FrontEndEmulator, FrontEndEmulatorDetailed, FrontEndGameTypeDetailed, EmulatorDownloadInfoType } from "../shared";
+import { AsyncSeriesBailHook, AsyncSeriesHook } from "tapable";
+
+export default class StoreHooks
+{
+    fetchFeaturedGames = new AsyncSeriesHook<[ctx: { games: FrontEndGameTypeDetailed[]; }]>(['ctx']);
+    fetchEmulators = new AsyncSeriesHook<[ctx: { emulators: FrontEndEmulator[]; search?: string; }]>(['ctx']);
+    fetchEmulator = new AsyncSeriesBailHook<[ctx: { id: string; }], FrontEndEmulatorDetailed | undefined>(['ctx']);
+    fetchDownload = new AsyncSeriesBailHook<[ctx: { id: string; }], (EmulatorDownloadInfoType & { hasUpdate: boolean; }) | undefined>(['ctx']);
+}

package/index.ts

@@ -0,0 +1,92 @@
+import z from "zod";
+import { GameflowHooks } from "./hooks/app";
+import { EmulatorDownloadInfoSchema, EmulatorPackageSchema, FrontendNotification, SettingsType } from "./shared";
+import { $ZodRegistry } from "zod/v4/core";
+import Conf from "conf";
+import { EventEmitter } from 'node:events';
+import { TaskQueue } from "./task-queue";
+
+export * from "./hooks/app";
+export * from "./task-queue";
+
+export interface AppEventMap
+{
+    exitapp: [];
+    notification: [FrontendNotification];
+    focus: [];
+}
+
+export const PluginContextSchema = z.object({
+    hooks: z.instanceof(GameflowHooks)
+});
+
+export const PluginLoadingContextSchema = z.object({
+    setProgress: z.function().input([z.number(), z.string()]).output(z.void()),
+    config: z.instanceof(Conf).describe("Per plugin config. It will use the settings schema defined in the plugin class"),
+    zodRegistry: z.instanceof($ZodRegistry).describe("Used by the settings to register metadata for the UI"),
+    app: z.object({
+        config: z.instanceof(Conf<SettingsType>),
+        events: z.instanceof(EventEmitter<AppEventMap>),
+        taskQueue: z.instanceof(TaskQueue)
+    })
+}).extend(PluginContextSchema.shape);
+
+export const PluginDescriptionSchema = z.object({
+    name: z.string(),
+    displayName: z.string().optional(),
+    version: z.string(),
+    description: z.string().optional(),
+    icon: z.url().optional().describe("Can be an external URL to an image or a data url"),
+    keywords: z.array(z.string()).optional(),
+    peerDependencies: z.record(z.string(), z.string()).optional(),
+    category: z.string().default("other"),
+    main: z.string().describe("The main entry. It must export a default class implementing PluginType"),
+    canDisable: z.boolean().default(true).optional().describe("Can the plugin be disabled or enabled by the user")
+});
+
+export const PluginSchema = z.object({
+    load: z.function().input([PluginLoadingContextSchema]).output(z.promise(z.void())).describe("Called when the plugin is loaded or reloaded"),
+    cleanup: z.function().output(z.promise(z.void())).optional().describe("Called when the plugin is unloaded or before it's reloaded"),
+    settingsSchema: z.instanceof(z.ZodObject).optional().describe("The settings schema. Gameflow will show settings in the UI."),
+    settingsMigrations: z.record(z.string(), z.function().input([z.instanceof(Conf)]).output(z.void())).optional(),
+    eventsNames: z.object({
+        id: z.string(),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        action: z.string()
+    }).array().optional().describe("Events will be called when the user presses the button in plugin settings. Each event creates a button."),
+    onEvent: z.function().input([z.string()]).output(z.object({
+        openTab: z.string().optional(),
+        reload: z.boolean().optional()
+    }).or(z.record(z.string(), z.any()))).optional()
+});
+
+export const ActiveGameSchema = z.object({
+    process: z.any().optional(),
+    gameId: z.object({ id: z.string(), source: z.string() }),
+    source: z.string().optional(),
+    sourceId: z.string().optional(),
+    name: z.string(),
+    command: z.object({ command: z.string().or(z.string().array()), startDir: z.string().optional() })
+});
+
+export const EmulatorPostInstallContextSchema = z.object({
+    emulator: z.string(),
+    emulatorPackage: EmulatorPackageSchema.optional(),
+    path: z.string(),
+    update: z.boolean(),
+    info: EmulatorDownloadInfoSchema,
+});
+
+export type ActiveGameType = z.infer<typeof ActiveGameSchema>;
+export type PluginDescriptionType = z.infer<typeof PluginDescriptionSchema>;
+export type PluginContextType = z.infer<typeof PluginContextSchema>;
+export type PluginLoadingContextType<TSettings extends Record<string, any> = Record<string, any>> = z.infer<typeof PluginLoadingContextSchema> & {
+    config: Conf<TSettings>;
+};
+export type PluginType<T extends Record<string, any> = Record<string, any>> = Omit<z.infer<typeof PluginSchema>, "load" | 'settingsMigrations'> & {
+    load: (ctx: PluginLoadingContextType<T>) => Promise<void>;
+    settingsMigrations?: Record<string, (conf: Conf<T>) => void>;
+};
+export type EmulatorPostInstallContextType = z.infer<typeof EmulatorPostInstallContextSchema>;
+

package/package.json

@@ -1,54 +1,51 @@
 {
-   "name": "@simeonradivoev/gameflow-sdk",
-   "version": "1.5.1",
-   "types": "index.d.ts",
-   "description": "plugin SDK for the Gameflow Deck Launcher",
-   "keywords": [
-      "gameflow",
-      "sdk"
-   ],
-   "license": "AGPL-3.0",
-   "repository": {
-      "type": "git",
-      "url": "https://github.com/simeonradivoev/gameflow-deck"
-   },
-   "author": {
-      "name": "Simeon Radivoev",
-      "email": "work@simeonradivoev.com",
-      "url": "https://simeonradivoev.com"
-   },
-   "peerDependencies": {
-      "7zip-bin": "^5.2.0",
-      "@auth/core": "^0.34.3",
-      "@elysiajs/cors": "^1.4.2",
-      "@elysiajs/eden": "^1.4.9",
-      "@jimp/wasm-webp": "^1.6.1",
-      "@phalcode/ts-igdb-client": "^1.0.26",
-      "cheerio": "^1.2.0",
-      "conf": "^15.1.0",
-      "drizzle-orm": "^0.45.2",
-      "elysia": "^1.4.28",
-      "fs-extra": "^11.3.5",
-      "get-folder-size": "^5.0.0",
-      "ini": "^6.0.0",
-      "jimp": "^1.6.1",
-      "mustache": "^4.2.0",
-      "node-7z": "^3.0.0",
-      "node-disk-info": "^1.3.0",
-      "node-downloader-helper": "^2.1.11",
-      "node-stream-zip": "^1.15.0",
-      "node-unrar-js": "^2.0.2",
-      "open": "^11.0.0",
-      "p-queue": "^9.2.0",
-      "pathe": "^2.0.3",
-      "slugify": "^1.6.9",
-      "smol-toml": "^1.6.1",
-      "systeminformation": "^5.31.5",
-      "tapable": "^2.3.3",
-      "tough-cookie": "^6.0.1",
-      "tough-cookie-file-store": "^3.3.0",
-      "unzip-stream": "^0.3.4",
-      "webview-bun": "^2.4.0",
-      "zod": "^4.4.3"
-   }
-}
+    "name": "@simeonradivoev/gameflow-sdk",
+    "version": "1.6.0",
+    "types": "index.d.ts",
+    "description": "plugin SDK for the Gameflow Deck Launcher",
+    "exports": {
+        ".": "./index.ts",
+        "./shared": "./shared.ts"
+    },
+    "bin": {
+        "gameflow-build": "build.ts"
+    },
+    "peerDependencies": {
+        "7zip-bin": "^5.2.0",
+        "@auth/core": "^0.34.3",
+        "@elysiajs/cors": "^1.4.2",
+        "@elysiajs/eden": "^1.4.9",
+        "@jimp/wasm-webp": "^1.6.1",
+        "@phalcode/ts-igdb-client": "^1.0.26",
+        "cheerio": "^1.2.0",
+        "conf": "^15.1.0",
+        "drizzle-orm": "^0.45.2",
+        "elysia": "^1.4.28",
+        "fs-extra": "^11.3.5",
+        "get-folder-size": "^5.0.0",
+        "ini": "^6.0.0",
+        "jimp": "^1.6.1",
+        "mustache": "^4.2.0",
+        "node-7z": "^3.0.0",
+        "node-disk-info": "^1.3.0",
+        "node-downloader-helper": "^2.1.11",
+        "node-stream-zip": "^1.15.0",
+        "node-unrar-js": "^2.0.2",
+        "open": "^11.0.0",
+        "p-queue": "^9.2.0",
+        "pathe": "^2.0.3",
+        "slugify": "^1.6.9",
+        "smol-toml": "^1.6.1",
+        "systeminformation": "^5.31.5",
+        "tapable": "^2.3.3",
+        "tough-cookie": "^6.0.1",
+        "tough-cookie-file-store": "^3.3.0",
+        "unzip-stream": "^0.3.4",
+        "webview-bun": "^2.4.0",
+        "zod": "^4.4.3"
+    },
+    "keywords": [
+        "gameflow",
+        "sdk"
+    ]
+}

package/sdk.tsconfig.json

@@ -0,0 +1,22 @@
+{
+   "compilerOptions": {
+      "target": "ES2022",
+      "useDefineForClassFields": true,
+      "lib": [
+         "ES2024"
+      ],
+      "module": "ESNext",
+      "skipLibCheck": true,
+      "moduleResolution": "bundler",
+      "allowImportingTsExtensions": true,
+      "isolatedModules": true,
+      "moduleDetection": "force",
+      "emitDeclarationOnly": true,
+      "declaration": true,
+      "strict": true,
+      "outDir": "../../dist-sdk",
+      "types": [
+         "node"
+      ]
+   }
+}