@zhin.js/contract 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/constants.d.ts

@@ -0,0 +1,5 @@
+/** Host API + plugin entry routes (entries, esm, @assets). Remote UI uses root paths (/dashboard, …). */
+export declare const DEFAULT_CONSOLE_BASE_PATH = "/";
+export declare const CONSOLE_HOST_REACT_NAMESPACE_KEY = "__ZHIN_CONSOLE_HOST_REACT_NAMESPACE__";
+export declare const CONSOLE_SHARED_MODULES_KEY = "__ZHIN_CONSOLE_SHARED_MODULES__";
+//# sourceMappingURL=constants.d.ts.map

package/lib/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,yGAAyG;AACzG,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,eAAO,MAAM,gCAAgC,0CAA0C,CAAC;AAExF,eAAO,MAAM,0BAA0B,oCAAoC,CAAC"}

package/lib/constants.js

@@ -0,0 +1,5 @@
+/** Host API + plugin entry routes (entries, esm, @assets). Remote UI uses root paths (/dashboard, …). */
+export const DEFAULT_CONSOLE_BASE_PATH = "/";
+export const CONSOLE_HOST_REACT_NAMESPACE_KEY = "__ZHIN_CONSOLE_HOST_REACT_NAMESPACE__";
+export const CONSOLE_SHARED_MODULES_KEY = "__ZHIN_CONSOLE_SHARED_MODULES__";
+//# sourceMappingURL=constants.js.map

package/lib/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,yGAAyG;AACzG,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAE7C,MAAM,CAAC,MAAM,gCAAgC,GAAG,uCAAuC,CAAC;AAExF,MAAM,CAAC,MAAM,0BAA0B,GAAG,iCAAiC,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,90 @@
+export { DEFAULT_CONSOLE_BASE_PATH, CONSOLE_HOST_REACT_NAMESPACE_KEY, CONSOLE_SHARED_MODULES_KEY, } from "./constants.js";
+export type RuntimeEnv = "development" | "production";
+export type ConsoleUser = {
+    id: string;
+    name: string;
+    roles?: string[];
+    permissions: string[];
+};
+export type ConsoleAuthContext = unknown;
+export type ConsoleAuthAdapter = {
+    getUser(ctx: ConsoleAuthContext): Promise<ConsoleUser | null> | ConsoleUser | null;
+    hasPermission(user: ConsoleUser, permission: string): boolean;
+};
+export type EntryModuleSpec = string | {
+    dev: string;
+    prod?: string;
+};
+export type ConsoleEntryPaths = {
+    development: string;
+    production: string;
+};
+export type ConsoleEntry = {
+    id: string;
+    paths?: ConsoleEntryPaths;
+    serverPaths?: {
+        development: string;
+        production: string;
+    };
+    module?: EntryModuleSpec;
+    packageEntry?: string;
+    order?: number;
+    enabled?: boolean;
+    meta?: {
+        name?: string;
+        version?: string;
+    };
+    requiredPermissions?: string[];
+};
+export type ConsoleFileAddEntryInput = {
+    id?: string;
+    development: string;
+    production: string;
+    serverDevelopment?: string;
+    serverProduction?: string;
+    order?: number;
+    enabled?: boolean;
+    meta?: {
+        name?: string;
+        version?: string;
+    };
+    requiredPermissions?: string[];
+};
+export type ConsoleClientEntry = Omit<ConsoleEntry, "serverPaths"> & {
+    resolvedModule: string;
+};
+export type PluginAddRouteInput = {
+    path: string;
+    name: string;
+    element: unknown;
+    parent?: string | null;
+    icon?: unknown;
+    meta?: {
+        hideInMenu?: boolean;
+        order?: number;
+        group?: string;
+        fullWidth?: boolean;
+    };
+    requiredPermissions?: string[];
+    requiredRoles?: string[];
+};
+export type PluginAddToolInput = {
+    id?: string;
+    name: string;
+    icon?: unknown;
+    parent?: string | null;
+    path?: string;
+};
+export type PluginRegisterHostApi = {
+    React: typeof import("react");
+    addRoute(input: PluginAddRouteInput): void;
+    /** 与旧版控制台 register(api) 对齐，等价于 addRoute */
+    addPage(input: PluginAddRouteInput): void;
+    addTool(input: PluginAddToolInput): string;
+};
+export type ConsolePluginRegister = (api: PluginRegisterHostApi) => void | Promise<void>;
+export type ConsoleEntriesResponse = {
+    entries: ConsoleClientEntry[];
+    runtimeEnvHint: RuntimeEnv | null;
+};
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/index.js

@@ -0,0 +1,2 @@
+export { DEFAULT_CONSOLE_BASE_PATH, CONSOLE_HOST_REACT_NAMESPACE_KEY, CONSOLE_SHARED_MODULES_KEY, } from "./constants.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@zhin.js/contract",
+  "version": "1.0.0",
+  "description": "Zhin console / PageManager shared contract (entries, PluginRegisterHostApi)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "devDependencies": {
+    "@types/react": "^19.2.15",
+    "rimraf": "^6.0.1",
+    "typescript": "^6.0.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/console/contract"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rimraf lib",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,6 @@
+/** Host API + plugin entry routes (entries, esm, @assets). Remote UI uses root paths (/dashboard, …). */
+export const DEFAULT_CONSOLE_BASE_PATH = "/";
+
+export const CONSOLE_HOST_REACT_NAMESPACE_KEY = "__ZHIN_CONSOLE_HOST_REACT_NAMESPACE__";
+
+export const CONSOLE_SHARED_MODULES_KEY = "__ZHIN_CONSOLE_SHARED_MODULES__";

package/src/index.ts

@@ -0,0 +1,100 @@
+export {
+  DEFAULT_CONSOLE_BASE_PATH,
+  CONSOLE_HOST_REACT_NAMESPACE_KEY,
+  CONSOLE_SHARED_MODULES_KEY,
+} from "./constants.js";
+
+export type RuntimeEnv = "development" | "production";
+
+export type ConsoleUser = {
+  id: string;
+  name: string;
+  roles?: string[];
+  permissions: string[];
+};
+
+export type ConsoleAuthContext = unknown;
+
+export type ConsoleAuthAdapter = {
+  getUser(ctx: ConsoleAuthContext): Promise<ConsoleUser | null> | ConsoleUser | null;
+  hasPermission(user: ConsoleUser, permission: string): boolean;
+};
+
+export type EntryModuleSpec =
+  | string
+  | {
+      dev: string;
+      prod?: string;
+    };
+
+export type ConsoleEntryPaths = {
+  development: string;
+  production: string;
+};
+
+export type ConsoleEntry = {
+  id: string;
+  paths?: ConsoleEntryPaths;
+  serverPaths?: { development: string; production: string };
+  module?: EntryModuleSpec;
+  packageEntry?: string;
+  order?: number;
+  enabled?: boolean;
+  meta?: { name?: string; version?: string };
+  requiredPermissions?: string[];
+};
+
+export type ConsoleFileAddEntryInput = {
+  id?: string;
+  development: string;
+  production: string;
+  serverDevelopment?: string;
+  serverProduction?: string;
+  order?: number;
+  enabled?: boolean;
+  meta?: { name?: string; version?: string };
+  requiredPermissions?: string[];
+};
+
+export type ConsoleClientEntry = Omit<ConsoleEntry, "serverPaths"> & {
+  resolvedModule: string;
+};
+
+export type PluginAddRouteInput = {
+  path: string;
+  name: string;
+  element: unknown;
+  parent?: string | null;
+  icon?: unknown;
+  meta?: {
+    hideInMenu?: boolean;
+    order?: number;
+    group?: string;
+    fullWidth?: boolean;
+  };
+  requiredPermissions?: string[];
+  requiredRoles?: string[];
+};
+
+export type PluginAddToolInput = {
+  id?: string;
+  name: string;
+  icon?: unknown;
+  parent?: string | null;
+  path?: string;
+};
+
+export type PluginRegisterHostApi = {
+  React: typeof import("react");
+  addRoute(input: PluginAddRouteInput): void;
+  /** 与旧版控制台 register(api) 对齐，等价于 addRoute */
+  addPage(input: PluginAddRouteInput): void;
+  addTool(input: PluginAddToolInput): string;
+};
+
+export type ConsolePluginRegister = (api: PluginRegisterHostApi) => void | Promise<void>;
+
+export type ConsoleEntriesResponse = {
+  entries: ConsoleClientEntry[];
+  runtimeEnvHint: RuntimeEnv | null;
+};