@qpjoy/electron-plugin-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @qpjoy/electron-plugin-sdk
+ *
+ * Public surface for plugin authors. Importing anything else from
+ * `@qpjoy/electron-market` directly is **not** part of the contract and may
+ * break across host versions.
+ */
+export declare const PLUGIN_SPEC_VERSION: 1;
+/**
+ * Static permission strings. Anything that needs a parameter uses the
+ * `category:scope[:detail]` form so it can be parsed without changing the
+ * type for every new resource.
+ */
+export type Permission = 'fs:userData' | 'fs:any' | `net:listen:${number}` | `net:listen:${number}-${number}` | `net:fetch:${string}` | 'system:proxy' | `system:exec:${string}` | `ipc:${string}` | 'ipc:cross' | 'ui:adminPanel';
+export type ActivationEvent = 'onStartup' | `onCommand:${string}` | `onSetting:${string}`;
+export interface PluginManifest {
+    /** Stable id, reverse-DNS style. NOT the npm name. */
+    id: string;
+    name: string;
+    version: string;
+    author?: string;
+    description?: string;
+    homepage?: string;
+    engines: {
+        /** semver range against @qpjoy/electron-market (the host runtime). */
+        electronMarket?: string;
+        /**
+         * Legacy alias for `electronMarket`. Accepted by hosts >= 0.2.0 so
+         * plugins published against the pre-rename spec still load.
+         * New plugins should use `electronMarket`.
+         * @deprecated Use `electronMarket`.
+         */
+        electronPlugin?: string;
+        /** semver range against electron itself */
+        electron?: string;
+    };
+    permissions: Permission[];
+    activationEvents: ActivationEvent[];
+    contributes?: {
+        adminPanel?: {
+            url: string;
+            label?: string;
+        };
+        settings?: {
+            schema: string;
+        };
+        commands?: Array<{
+            id: string;
+            title: string;
+        }>;
+    };
+}
+export interface PluginHostBridge {
+    /** A reduced electron triple. The full one is gated behind permissions. */
+    app: import('electron').App;
+    ipcMain: import('electron').IpcMain;
+    session: import('electron').Session;
+    /** Ask the host to re-apply session proxy. Requires `system:proxy`. */
+    applyProxy(): Promise<void>;
+}
+export interface PluginContext<S = unknown> {
+    readonly manifest: PluginManifest;
+    readonly host: PluginHostBridge;
+    /** Sandbox dir, always inside `userData/plugins/<id>/`. */
+    readonly userDataDir: string;
+    /** Persistent settings store. Schema is whatever the plugin wants. */
+    readonly settings: {
+        get(): S;
+        set(next: Partial<S>): void;
+        onChange(listener: (next: S) => void): () => void;
+    };
+    /** Convenience wrapper around `settings.onChange`. */
+    onConfigChange(listener: (next: S) => void): () => void;
+    /**
+     * Cross-plugin RPC. Requires `ipc:cross` on both sides.
+     *
+     * The function parameter type uses `any[]` rather than `unknown[]` so that
+     * authors can pass concretely-typed methods (e.g. `(id: number) => Promise<void>`)
+     * without casts. The runtime never inspects the signature; only the method
+     * names are dispatched.
+     */
+    expose(api: Record<string, (...args: any[]) => any>): void;
+    call<T = unknown>(pluginId: string, method: string, ...args: unknown[]): Promise<T>;
+    /** Permission-gated helpers — throw `PermissionDeniedError` if not granted. */
+    spawn(bin: string, args: string[], opts?: {
+        cwd?: string;
+    }): import('child_process').ChildProcess;
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /** Structured logger that surfaces in the 23455 admin panel. */
+    readonly log: {
+        info(msg: string, meta?: Record<string, unknown>): void;
+        warn(msg: string, meta?: Record<string, unknown>): void;
+        error(msg: string, meta?: Record<string, unknown>): void;
+    };
+}
+export declare class PermissionDeniedError extends Error {
+    readonly permission: Permission;
+    constructor(permission: Permission);
+}
+/** A plugin returns a disposer; the host calls it on deactivate / uninstall. */
+export type PluginDispose = () => void | Promise<void>;
+export interface PluginModule<S = unknown> {
+    activate(ctx: PluginContext<S>): Promise<PluginDispose | void> | PluginDispose | void;
+    /** Optional; defaults to invoking the disposer returned by `activate`. */
+    deactivate?(ctx: PluginContext<S>): Promise<void> | void;
+}
+/** Identity function. Exists for typing and future codegen / static analysis. */
+export declare function definePlugin<S = unknown>(mod: PluginModule<S>): PluginModule<S>;

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * @qpjoy/electron-plugin-sdk
+ *
+ * Public surface for plugin authors. Importing anything else from
+ * `@qpjoy/electron-market` directly is **not** part of the contract and may
+ * break across host versions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionDeniedError = exports.PLUGIN_SPEC_VERSION = void 0;
+exports.definePlugin = definePlugin;
+exports.PLUGIN_SPEC_VERSION = 1;
+class PermissionDeniedError extends Error {
+    permission;
+    constructor(permission) {
+        super(`Permission denied: ${permission}`);
+        this.permission = permission;
+        this.name = 'PermissionDeniedError';
+    }
+}
+exports.PermissionDeniedError = PermissionDeniedError;
+/** Identity function. Exists for typing and future codegen / static analysis. */
+function definePlugin(mod) {
+    return mod;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@qpjoy/electron-plugin-sdk",
+  "version": "0.1.0",
+  "description": "Types and helpers for authoring QPJoy electron plugins (definePlugin, Permission catalog, PluginContext).",
+  "license": "UNLICENSED",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "electron",
+    "plugin",
+    "sdk",
+    "qpjoy",
+    "marketplace"
+  ],
+  "homepage": "https://github.com/qpjoy/electron-plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/qpjoy/electron-plugin.git",
+    "directory": "packages/electron-plugin-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "electron": ">=28"
+  },
+  "peerDependenciesMeta": {
+    "electron": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "electron": "^34.0.0",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  }
+}