@fecommunity/reactpress-toolkit 3.0.4 → 3.7.0

package/dist/plugin/extension/plugin.js

@@ -0,0 +1,146 @@
+"use strict";
+/** WordPress-style plugin manifest and site plugin state (shared by server / web). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_ADMIN_MODULE_CONVENTION = exports.defaultSitePluginState = void 0;
+exports.isValidPluginId = isValidPluginId;
+exports.parsePluginManifest = parsePluginManifest;
+exports.getPluginStateFromGlobalSetting = getPluginStateFromGlobalSetting;
+exports.mergePluginStateIntoGlobalSetting = mergePluginStateIntoGlobalSetting;
+exports.pluginManifestHasAdminUI = pluginManifestHasAdminUI;
+const slots_1 = require("../admin/slots");
+const security_1 = require("./security");
+exports.defaultSitePluginState = {
+    installedPlugins: [],
+    activePlugins: [],
+    entries: {},
+};
+const PLUGIN_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function isValidPluginId(id) {
+    return typeof id === 'string' && PLUGIN_ID_RE.test(id) && id.length <= 64;
+}
+function parsePluginManifest(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const o = raw;
+    if (typeof o.id !== 'string' || typeof o.name !== 'string')
+        return null;
+    if (!isValidPluginId(o.id))
+        return null;
+    const serverRaw = o.server;
+    const server = serverRaw && typeof serverRaw === 'object'
+        ? (() => {
+            const moduleRaw = serverRaw.module;
+            const modulePath = typeof moduleRaw === 'string' ? moduleRaw.trim() : '';
+            if (!modulePath || !(0, security_1.isSafePluginModuleRel)(modulePath)) {
+                return undefined;
+            }
+            return {
+                module: modulePath,
+                hooks: serverRaw.hooks &&
+                    typeof serverRaw.hooks === 'object'
+                    ? {
+                        subscribe: Array.isArray(serverRaw.hooks
+                            .subscribe)
+                            ? serverRaw.hooks
+                                .subscribe.filter((h) => typeof h === 'string')
+                            : undefined,
+                        provide: Array.isArray(serverRaw.hooks
+                            .provide)
+                            ? serverRaw.hooks
+                                .provide.filter((h) => typeof h === 'string')
+                            : undefined,
+                    }
+                    : undefined,
+            };
+        })()
+        : undefined;
+    const adminRaw = o.admin;
+    const admin = adminRaw && typeof adminRaw === 'object'
+        ? (() => {
+            const raw = adminRaw;
+            const slotsRaw = raw.slots;
+            const subscribe = slotsRaw &&
+                typeof slotsRaw === 'object' &&
+                Array.isArray(slotsRaw.subscribe)
+                ? slotsRaw.subscribe.filter((slot) => typeof slot === 'string' && (0, slots_1.isAdminSlotId)(slot))
+                : undefined;
+            return {
+                entry: typeof raw.entry === 'string' ? raw.entry : undefined,
+                slots: subscribe?.length ? { subscribe } : undefined,
+                menu: raw.menu && typeof raw.menu === 'object'
+                    ? raw.menu
+                    : undefined,
+            };
+        })()
+        : undefined;
+    const settingsRaw = o.settings;
+    const settings = settingsRaw && typeof settingsRaw === 'object'
+        ? {
+            schema: settingsRaw.schema &&
+                typeof settingsRaw.schema === 'object'
+                ? settingsRaw.schema
+                : undefined,
+        }
+        : undefined;
+    const capsRaw = o.capabilities;
+    const capabilities = capsRaw && typeof capsRaw === 'object'
+        ? capsRaw
+        : undefined;
+    return {
+        id: o.id,
+        name: o.name,
+        version: typeof o.version === 'string' ? o.version : '1.0.0',
+        description: typeof o.description === 'string' ? o.description : undefined,
+        author: typeof o.author === 'string' ? o.author : undefined,
+        requires: typeof o.requires === 'string' ? o.requires : undefined,
+        requiresPlugins: Array.isArray(o.requiresPlugins)
+            ? o.requiresPlugins.filter((p) => typeof p === 'string')
+            : undefined,
+        server: server?.module ? server : undefined,
+        admin,
+        settings,
+        permissions: Array.isArray(o.permissions)
+            ? o.permissions.filter((p) => typeof p === 'string')
+            : undefined,
+        capabilities,
+    };
+}
+function getPluginStateFromGlobalSetting(raw) {
+    if (!raw || typeof raw !== 'object')
+        return { ...exports.defaultSitePluginState };
+    const gs = raw;
+    const plugins = gs.plugins;
+    if (!plugins || typeof plugins !== 'object')
+        return { ...exports.defaultSitePluginState };
+    return {
+        installedPlugins: Array.isArray(plugins.installedPlugins)
+            ? plugins.installedPlugins.filter((id) => typeof id === 'string' && isValidPluginId(id))
+            : [],
+        activePlugins: Array.isArray(plugins.activePlugins)
+            ? plugins.activePlugins.filter((id) => typeof id === 'string' && isValidPluginId(id))
+            : [],
+        entries: plugins.entries && typeof plugins.entries === 'object'
+            ? plugins.entries
+            : {},
+    };
+}
+function mergePluginStateIntoGlobalSetting(raw, patch) {
+    const base = raw && typeof raw === 'object'
+        ? { ...raw }
+        : {};
+    const current = getPluginStateFromGlobalSetting(base);
+    base.plugins = {
+        installedPlugins: patch.installedPlugins ?? current.installedPlugins,
+        activePlugins: patch.activePlugins ?? current.activePlugins,
+        entries: patch.entries ?? current.entries,
+    };
+    return base;
+}
+/** Conventional admin module path relative to plugin package root. */
+exports.PLUGIN_ADMIN_MODULE_CONVENTION = 'admin/index';
+/** Whether manifest declares admin UI (slot and/or settings menu). */
+function pluginManifestHasAdminUI(admin) {
+    if (!admin)
+        return false;
+    return Boolean(admin.menu || (admin.slots?.subscribe?.length ?? 0) > 0);
+}

package/dist/plugin/extension/security.d.ts

@@ -0,0 +1,7 @@
+/** Relative server entry path inside the plugin runtime directory (no `..`, no absolute paths). */
+export declare function isSafePluginModuleRel(moduleRel: string): boolean;
+/**
+ * Resolve `server.module` under the plugin root and ensure the result cannot escape it.
+ * Returns `null` when the path is unsafe or uses a disallowed extension.
+ */
+export declare function resolvePluginServerModulePath(pluginRoot: string, moduleRel: string): string | null;

package/dist/plugin/extension/security.js

@@ -0,0 +1,74 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSafePluginModuleRel = isSafePluginModuleRel;
+exports.resolvePluginServerModulePath = resolvePluginServerModulePath;
+const path = __importStar(require("path"));
+const ALLOWED_MODULE_EXTENSIONS = new Set(['.js', '.cjs', '.mjs']);
+/** Relative server entry path inside the plugin runtime directory (no `..`, no absolute paths). */
+function isSafePluginModuleRel(moduleRel) {
+    if (typeof moduleRel !== 'string' || !moduleRel.trim())
+        return false;
+    if (path.isAbsolute(moduleRel))
+        return false;
+    if (moduleRel.includes('\0'))
+        return false;
+    const normalized = moduleRel.replace(/^\.\//, '').replace(/\\/g, '/');
+    const segments = normalized.split('/');
+    if (segments.some((segment) => segment === '..'))
+        return false;
+    if (segments.some((segment) => segment === '.'))
+        return false;
+    return segments.every((segment) => segment.length > 0);
+}
+/**
+ * Resolve `server.module` under the plugin root and ensure the result cannot escape it.
+ * Returns `null` when the path is unsafe or uses a disallowed extension.
+ */
+function resolvePluginServerModulePath(pluginRoot, moduleRel) {
+    if (!isSafePluginModuleRel(moduleRel))
+        return null;
+    const rel = moduleRel.replace(/^\.\//, '');
+    const root = path.resolve(pluginRoot);
+    const resolved = path.resolve(root, rel);
+    if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+        return null;
+    }
+    const ext = path.extname(resolved).toLowerCase();
+    if (!ext || !ALLOWED_MODULE_EXTENSIONS.has(ext)) {
+        return null;
+    }
+    return resolved;
+}

package/dist/plugin/extension/validate.d.ts

@@ -0,0 +1,8 @@
+import { type ErrorObject } from 'ajv';
+export interface PluginSettingsValidationResult {
+    valid: boolean;
+    errors: ErrorObject[] | null;
+    message?: string;
+}
+export declare function assertPlainPluginConfig(config: unknown): Record<string, unknown>;
+export declare function validatePluginSettings(schema: Record<string, unknown> | null | undefined, data: unknown): PluginSettingsValidationResult;

package/dist/plugin/extension/validate.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertPlainPluginConfig = assertPlainPluginConfig;
+exports.validatePluginSettings = validatePluginSettings;
+const ajv_1 = __importDefault(require("ajv"));
+const ajv = new ajv_1.default({ allErrors: true, strict: false, coerceTypes: false });
+const FORBIDDEN_CONFIG_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function assertPlainPluginConfig(config) {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+        throw new Error('Plugin config must be a JSON object');
+    }
+    for (const key of Object.keys(config)) {
+        if (FORBIDDEN_CONFIG_KEYS.has(key)) {
+            throw new Error(`Invalid config key "${key}"`);
+        }
+    }
+    return config;
+}
+function validatePluginSettings(schema, data) {
+    if (!schema) {
+        if (data &&
+            typeof data === 'object' &&
+            !Array.isArray(data) &&
+            Object.keys(data).length > 0) {
+            return {
+                valid: false,
+                errors: null,
+                message: 'Plugin has no configurable settings',
+            };
+        }
+        return { valid: true, errors: null };
+    }
+    let config;
+    try {
+        config = assertPlainPluginConfig(data);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            errors: null,
+            message: err instanceof Error ? err.message : 'Invalid plugin config',
+        };
+    }
+    const validate = ajv.compile(schema);
+    const valid = validate(config) === true;
+    if (valid) {
+        return { valid: true, errors: null };
+    }
+    const errors = validate.errors ?? [];
+    const message = errors.map((e) => `${e.instancePath || '/'} ${e.message ?? ''}`.trim()).join('; ');
+    return { valid: false, errors, message: message || 'Invalid plugin configuration' };
+}

package/dist/plugin/index.d.ts

@@ -0,0 +1,9 @@
+export * as admin from './admin';
+export * as client from './client';
+export * as dev from './dev';
+/** @deprecated Use `plugin/client`; path kept for compatibility. */
+export * as react from './react';
+export * from './admin';
+export * from './client';
+export * from './dev';
+export * from './react';

package/dist/plugin/index.js

@@ -0,0 +1,48 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.react = exports.dev = exports.client = exports.admin = void 0;
+exports.admin = __importStar(require("./admin"));
+exports.client = __importStar(require("./client"));
+exports.dev = __importStar(require("./dev"));
+/** @deprecated Use `plugin/client`; path kept for compatibility. */
+exports.react = __importStar(require("./react"));
+__exportStar(require("./admin"), exports);
+__exportStar(require("./client"), exports);
+__exportStar(require("./dev"), exports);
+__exportStar(require("./react"), exports);

package/dist/plugin/node.d.ts

@@ -0,0 +1,2 @@
+/** Node-only plugin helpers (filesystem I/O). */
+export { readPluginAdminLocaleFile } from './extension/plugin-admin-locale.io';

package/dist/plugin/node.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPluginAdminLocaleFile = void 0;
+/** Node-only plugin helpers (filesystem I/O). */
+var plugin_admin_locale_io_1 = require("./extension/plugin-admin-locale.io");
+Object.defineProperty(exports, "readPluginAdminLocaleFile", { enumerable: true, get: function () { return plugin_admin_locale_io_1.readPluginAdminLocaleFile; } });

package/dist/plugin/react/client.d.ts

@@ -0,0 +1,14 @@
+import { createApiInstance } from '../../api/instance';
+export declare class ApiError extends Error {
+    code: number;
+    constructor(code: number, message: string);
+}
+export interface ClientOptions {
+    baseURL?: string;
+    getAccessToken?: () => string | null | undefined;
+    onUnauthorized?: () => void;
+}
+export type ReactPressClient = ReturnType<typeof createApiInstance>;
+/** Single factory for web / theme / plugins — wraps generated API modules. */
+export declare function createClient(options?: ClientOptions): ReactPressClient;
+export declare function getDefaultApiBaseUrl(): string;

package/dist/plugin/react/client.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiError = void 0;
+exports.createClient = createClient;
+exports.getDefaultApiBaseUrl = getDefaultApiBaseUrl;
+const instance_1 = require("../../api/instance");
+class ApiError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'ApiError';
+        this.code = code;
+    }
+}
+exports.ApiError = ApiError;
+function readApiMessage(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed ? trimmed : null;
+    }
+    if (Array.isArray(value)) {
+        const parts = value
+            .map((item) => readApiMessage(item))
+            .filter((item) => Boolean(item));
+        return parts.length ? parts.join(', ') : null;
+    }
+    if (value && typeof value === 'object') {
+        const payload = value;
+        return readApiMessage(payload.message) ?? readApiMessage(payload.msg);
+    }
+    return null;
+}
+function rejectApiError(status, payload) {
+    if (typeof payload.code === 'number' && payload.code !== 0) {
+        return Promise.reject(new ApiError(payload.code, readApiMessage(payload.message) ?? 'Request failed'));
+    }
+    const message = readApiMessage(payload.msg) ?? readApiMessage(payload.message);
+    if (message) {
+        return Promise.reject(new ApiError(Number(payload.statusCode ?? status ?? 500), message));
+    }
+    return null;
+}
+function attachInterceptors(http, options) {
+    http.instance.interceptors.request.use((config) => {
+        const token = options.getAccessToken?.();
+        if (token && config.headers) {
+            config.headers.Authorization = `Bearer ${token}`;
+        }
+        return config;
+    });
+    http.instance.interceptors.response.use((response) => {
+        const body = response.data;
+        if (!body || typeof body !== 'object')
+            return response;
+        if (typeof body.code === 'number') {
+            if (body.code !== 0) {
+                throw new ApiError(body.code, readApiMessage(body.message) ?? 'Request failed');
+            }
+            response.data = body.data;
+            return response;
+        }
+        if (typeof body.success === 'boolean') {
+            if (!body.success) {
+                throw new ApiError(Number(body.statusCode ?? 500), readApiMessage(body.msg) ?? 'Request failed');
+            }
+            response.data = body.data;
+            return response;
+        }
+        return response;
+    }, (error) => {
+        const status = error?.response?.status;
+        if (status === 401) {
+            options.onUnauthorized?.();
+        }
+        const body = error?.response?.data;
+        if (body && typeof body === 'object') {
+            const rejected = rejectApiError(status, body);
+            if (rejected)
+                return rejected;
+        }
+        return Promise.reject(error);
+    });
+}
+/** Single factory for web / theme / plugins — wraps generated API modules. */
+function createClient(options = {}) {
+    const baseURL = options.baseURL ?? 'http://localhost:3002/api';
+    const client = (0, instance_1.createApiInstance)({ baseURL });
+    attachInterceptors(client.article.http, options);
+    return client;
+}
+function getDefaultApiBaseUrl() {
+    if (typeof process !== 'undefined' && process.env?.SERVER_API_URL) {
+        return process.env.SERVER_API_URL;
+    }
+    return 'http://localhost:3002/api';
+}

package/dist/plugin/react/index.d.ts

@@ -0,0 +1,2 @@
+/** Stable export path: `@fecommunity/reactpress-toolkit/plugin/react`. */
+export * from '../client';

package/dist/plugin/react/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/** Stable export path: `@fecommunity/reactpress-toolkit/plugin/react`. */
+__exportStar(require("../client"), exports);

package/dist/plugin/react/plugin-admin-ui.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import type { PluginAdminSlotComponentProps, PluginAdminSlotContribution, PluginAdminSlotHost } from '../admin/plugin-admin';
+import type { AdminSlotId } from '../admin/slots';
+export interface PluginAdminRuntimeContextValue {
+    ready: boolean;
+    host: PluginAdminSlotHost;
+    configByPluginId: Record<string, Record<string, unknown>>;
+}
+export declare function PluginAdminRuntimeProvider({ value, children, }: {
+    value: PluginAdminRuntimeContextValue;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function usePluginAdminRuntime(): PluginAdminRuntimeContextValue;
+export declare function useAdminSlotContributions(slot: AdminSlotId): PluginAdminSlotContribution[];
+export declare function useAdminSlotFilled(slot: AdminSlotId): boolean;
+export interface AdminSlotProps<TContext> {
+    slot: AdminSlotId;
+    context: TContext;
+    className?: string;
+}
+/** Render all active plugin contributions registered for a slot. */
+export declare function AdminSlot<TContext>({ slot, context, className }: AdminSlotProps<TContext>): import("react/jsx-runtime").JSX.Element | null;
+export type { PluginAdminSlotComponentProps };

package/dist/plugin/react/plugin-admin-ui.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginAdminRuntimeProvider = PluginAdminRuntimeProvider;
+exports.usePluginAdminRuntime = usePluginAdminRuntime;
+exports.useAdminSlotContributions = useAdminSlotContributions;
+exports.useAdminSlotFilled = useAdminSlotFilled;
+exports.AdminSlot = AdminSlot;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const PluginAdminRuntimeContext = (0, react_1.createContext)(null);
+function PluginAdminRuntimeProvider({ value, children, }) {
+    return ((0, jsx_runtime_1.jsx)(PluginAdminRuntimeContext.Provider, { value: value, children: children }));
+}
+function usePluginAdminRuntime() {
+    const ctx = (0, react_1.useContext)(PluginAdminRuntimeContext);
+    if (!ctx) {
+        throw new Error('usePluginAdminRuntime must be used within PluginAdminRuntimeProvider');
+    }
+    return ctx;
+}
+function useAdminSlotContributions(slot) {
+    const { host, ready } = usePluginAdminRuntime();
+    return (0, react_1.useMemo)(() => (ready ? host.getContributions(slot) : []), [host, ready, slot]);
+}
+function useAdminSlotFilled(slot) {
+    return useAdminSlotContributions(slot).length > 0;
+}
+/** Render all active plugin contributions registered for a slot. */
+function AdminSlot({ slot, context, className }) {
+    const { ready, host, configByPluginId } = usePluginAdminRuntime();
+    const items = (0, react_1.useMemo)(() => (ready ? host.getContributions(slot) : []), [host, ready, slot]);
+    if (!ready || items.length === 0)
+        return null;
+    return ((0, jsx_runtime_1.jsx)("div", { className: className, "data-admin-slot": slot, children: items.map(({ pluginId, Component }) => {
+            const Render = Component;
+            return ((0, jsx_runtime_1.jsx)(Render, { pluginId: pluginId, config: configByPluginId[pluginId] ?? {}, context: context }, pluginId));
+        }) }));
+}

package/dist/plugin/react/runtime.d.ts

@@ -0,0 +1,18 @@
+export type AppRuntime = 'web' | 'electron';
+export interface DesktopApi {
+    getApiBaseUrl: () => Promise<string>;
+    setApiBaseUrl: (url: string) => Promise<void>;
+    showSaveDialog: (opts: {
+        defaultPath?: string;
+    }) => Promise<string | undefined>;
+    openExternal: (url: string) => Promise<void>;
+    platform: NodeJS.Platform;
+}
+declare global {
+    interface Window {
+        reactpressDesktop?: DesktopApi;
+    }
+}
+export declare function getRuntime(): AppRuntime;
+export declare function getDesktopApi(): DesktopApi | undefined;
+export declare function resolveApiBaseUrl(fallback: string): Promise<string>;

package/dist/plugin/react/runtime.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRuntime = getRuntime;
+exports.getDesktopApi = getDesktopApi;
+exports.resolveApiBaseUrl = resolveApiBaseUrl;
+function getRuntime() {
+    if (typeof window !== 'undefined' && window.reactpressDesktop) {
+        return 'electron';
+    }
+    return 'web';
+}
+function getDesktopApi() {
+    if (typeof window === 'undefined')
+        return undefined;
+    return window.reactpressDesktop;
+}
+async function resolveApiBaseUrl(fallback) {
+    const desktop = getDesktopApi();
+    if (desktop) {
+        try {
+            const url = await desktop.getApiBaseUrl();
+            if (url)
+                return url;
+        }
+        catch {
+            // fall through
+        }
+    }
+    return fallback;
+}

package/dist/plugin/server/hook-reject.d.ts

@@ -0,0 +1,12 @@
+/** Filter 回调可通过 `__hookReject` 拒绝继续处理（由核心 Service 识别并抛出 HTTP 错误）。 */
+export declare const HOOK_REJECT_KEY = "__hookReject";
+export interface HookRejectMeta {
+    message: string;
+    statusCode?: number;
+}
+export declare function createHookRejectValue<T extends Record<string, unknown>>(value: T, reject: HookRejectMeta): T & {
+    __hookReject: HookRejectMeta;
+};
+export declare function getHookReject(value: unknown): HookRejectMeta | null;
+export declare function sanitizeHookRejectStatusCode(statusCode?: number): number;
+export declare function stripHookMeta<T extends Record<string, unknown>>(value: T): T;

package/dist/plugin/server/hook-reject.js

@@ -0,0 +1,39 @@
+"use strict";
+/** Filter 回调可通过 `__hookReject` 拒绝继续处理（由核心 Service 识别并抛出 HTTP 错误）。 */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_REJECT_KEY = void 0;
+exports.createHookRejectValue = createHookRejectValue;
+exports.getHookReject = getHookReject;
+exports.sanitizeHookRejectStatusCode = sanitizeHookRejectStatusCode;
+exports.stripHookMeta = stripHookMeta;
+exports.HOOK_REJECT_KEY = '__hookReject';
+function createHookRejectValue(value, reject) {
+    return { ...value, [exports.HOOK_REJECT_KEY]: reject };
+}
+function getHookReject(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const reject = value[exports.HOOK_REJECT_KEY];
+    if (!reject || typeof reject !== 'object')
+        return null;
+    const message = reject.message;
+    if (typeof message !== 'string' || !message.trim())
+        return null;
+    return reject;
+}
+function sanitizeHookRejectStatusCode(statusCode) {
+    if (typeof statusCode !== 'number' || !Number.isInteger(statusCode)) {
+        return 400;
+    }
+    if (statusCode < 400 || statusCode > 599) {
+        return 400;
+    }
+    return statusCode;
+}
+function stripHookMeta(value) {
+    if (!(exports.HOOK_REJECT_KEY in value))
+        return value;
+    const next = { ...value };
+    delete next[exports.HOOK_REJECT_KEY];
+    return next;
+}