@lobehub/market-sdk 0.0.27 → 0.0.29

package/dist/index.d.mts

@@ -1,675 +1,888 @@
-import { ConnectionType, PluginCompatibility, PluginManifest, AdminPluginItem, AdminDeploymentOption, SystemDependency } from '@lobehub/market-types';
+import { PluginManifest, PluginCompatibility, ConnectionType, AdminPluginItem, AdminPluginItemDetail, PluginVersion, AdminDeploymentOption, InstallationDetails, SystemDependency } from '@lobehub/market-types';
 export * from '@lobehub/market-types';
 import { z } from 'zod';
 
 /**
- * 市场服务发现文档
+ * Visibility levels for plugins in the marketplace
+ * - public: Visible to all users
+ * - private: Visible only to the owner and authorized users
+ * - internal: Visible only within the organization
  */
-interface DiscoveryDocument {
-    issuer: string;
-    market_index_schema_version: number;
-    resource_types_supported: string[];
-    resource_endpoints: Record<string, string>;
-    manifest_endpoint_template: string | Record<string, string>;
-    support_locales: string[];
-    response_types_supported: string[];
-    authentication?: {
-        schemes_supported: Array<'none' | 'apiKey' | 'oauth2'>;
-    };
-    api_documentation_url?: string;
-    policy_url?: string;
-    terms_of_service_url?: string;
-}
+declare const VisibilityEnumSchema: z.ZodEnum<["public", "private", "internal"]>;
 /**
- * SDK 配置选项
+ * Publication status options for plugins
+ * - published: Publicly available in the marketplace
+ * - unpublished: Not publicly visible
+ * - archived: Marked as no longer maintained
+ * - deprecated: Marked as deprecated, but still available
  */
-interface MarketSDKOptions {
-    baseURL?: string;
-    defaultLocale?: string;
-    apiKey?: string;
-}
-
-interface PluginItem {
-    identifier: string;
-    version: string;
-    isLatest: boolean;
-    name: string;
-    createdAt: string;
-    manifestUrl?: string;
-    manifestVersion: string;
-    icon?: string;
-    author?: string;
-    homepage?: string;
-    category?: string;
-    connectionType?: ConnectionType;
-    compatibility?: PluginCompatibility;
-    capabilities: {
-        tools: boolean;
-        prompts: boolean;
-        resources: boolean;
-    };
-    description: string;
-    tags?: string[];
-    authRequirement?: string;
-    isInstallable?: boolean;
-    toolsCount?: number;
-    promptsCount?: number;
-    resourcesCount?: number;
-    isValidated?: boolean;
-    installCount?: number;
-    ratingAverage?: number;
-    ratingCount?: number;
-    commentCount?: number;
-}
-interface PluginListResponse {
-    items: PluginItem[];
-    totalCount: number;
-    currentPage: number;
-    pageSize: number;
-    totalPages: number;
-    categories: string[];
-    tags: string[];
-}
-interface PluginQueryParams {
-    page?: number;
-    pageSize?: number;
-    category?: string;
-    tags?: string;
-    q?: string;
-    sort?: 'installCount' | 'createdAt' | 'updatedAt' | 'ratingAverage';
-    order?: 'asc' | 'desc';
-    locale?: string;
-}
-
-declare const VisibilityEnumSchema: z.ZodEnum<["public", "private", "internal"]>;
 declare const StatusEnumSchema: z.ZodEnum<["published", "unpublished", "archived", "deprecated"]>;
 /**
- * 通用列表查询参数
+ * Common query parameters for admin list endpoints
+ * These parameters are used for pagination, filtering, and sorting.
  */
 interface AdminListQueryParams {
+    /** Current page number (1-based) */
     current?: number;
+    /** Search keyword for filtering results */
+    keyword?: string;
+    /** Number of items per page */
     pageSize?: number;
+    /** Field to sort results by */
     sortField?: string;
+    /** Sort direction */
     sortOrder?: 'ascend' | 'descend';
-    keyword?: string;
 }
 /**
- * 通用列表响应格式
+ * Common response format for paginated admin list endpoints
+ * This structure provides both the data and pagination information.
  */
 interface AdminListResponse<T> {
+    /** Current page number (1-based) */
+    current: number;
+    /** Array of items for the current page */
     data: T[];
+    /** Number of items per page */
+    pageSize: number;
+    /** Total number of items across all pages */
     total: number;
+    /** Total number of pages */
     totalPages: number;
-    current: number;
-    pageSize: number;
 }
 /**
- * 插件版本数据库模型
+ * Review status options
+ * - pending: Awaiting review
+ * - approved: Review approved
+ * - rejected: Review rejected
  */
-interface PluginVersion {
-    id: number;
-    pluginId: number;
-    version: string;
-    isLatest: boolean;
-    manifestUrl: string | null;
-    toolsCount: number;
-    promptsCount: number;
-    resourcesCount: number;
-    isValidated: boolean;
-    createdAt: string;
-    updatedAt: string;
-    manifest: PluginManifest;
-    meta: Record<string, any> | null;
-}
 type ReviewStatus = 'pending' | 'approved' | 'rejected';
+/**
+ * Review status schema for validation
+ */
 declare const ReviewStatusEnumSchema: z.ZodEnum<["published", "draft", "review", "rejected"]>;
 /**
- * 管理员获取插件列表参数
+ * Parameters for admin plugin listing
+ * Extends the common query parameters with plugin-specific filters.
  */
 interface AdminPluginParams {
-    status?: 'published' | 'draft' | 'review' | 'rejected';
-    visibility?: 'public' | 'private' | 'unlisted';
+    /** Filter for featured plugins */
     featured?: boolean;
-    ownerId?: number;
+    /** Maximum number of items to return */
     limit?: number;
+    /** Number of items to skip */
     offset?: number;
-    query?: string;
-    orderBy?: 'createdAt' | 'updatedAt' | 'installCount' | 'ratingAverage';
+    /** Sort direction */
     order?: 'asc' | 'desc';
+    /** Field to sort by */
+    orderBy?: 'createdAt' | 'updatedAt' | 'installCount' | 'ratingAverage';
+    /** Filter by owner ID */
+    ownerId?: number;
+    /** Search query string */
+    query?: string;
+    /** Filter by plugin status */
+    status?: 'published' | 'draft' | 'review' | 'rejected';
+    /** Filter by visibility level */
+    visibility?: 'public' | 'private' | 'unlisted';
 }
 /**
- * 创建插件版本参数
+ * Parameters for creating a new plugin version
  */
 interface PluginVersionCreateParams {
-    version: string;
-    manifest: PluginManifest;
-    manifestUrl?: string;
+    /** Whether this is the latest version */
     isLatest?: boolean;
+    /** Whether this version has been validated */
     isValidated?: boolean;
+    /** The complete plugin manifest */
+    manifest: PluginManifest;
+    /** Optional URL to the manifest file */
+    manifestUrl?: string;
+    /** Additional metadata for the version */
     meta?: Record<string, any>;
+    /** Semantic version string (e.g., "1.0.0") */
+    version: string;
 }
 /**
- * 更新插件版本参数
+ * Parameters for updating an existing plugin version
  */
 interface PluginVersionUpdateParams {
-    manifestUrl?: string;
+    /** Whether this version has been validated */
     isValidated?: boolean;
+    /** URL to the manifest file */
+    manifestUrl?: string;
+    /** Additional metadata for the version */
     meta?: Record<string, any>;
 }
 /**
- * 更新插件信息参数
+ * Parameters for updating a plugin
  */
 interface PluginUpdateParams {
+    /** Unique identifier for the plugin */
     identifier?: string;
-    visibility?: 'public' | 'private' | 'unlisted';
-    status?: 'published' | 'draft' | 'review' | 'rejected';
+    /** Whether this plugin is featured */
     isFeatured?: boolean;
-    tags?: string[];
+    /** Additional metadata for the plugin */
     meta?: Record<string, any>;
+    /** Publication status */
+    status?: 'published' | 'draft' | 'review' | 'rejected';
+    /** Tags for categorization */
+    tags?: string[];
+    /** Visibility level */
+    visibility?: 'public' | 'private' | 'unlisted';
+}
+
+/**
+ * Market Service Discovery Document
+ *
+ * Defines the structure of the discovery document returned by the API.
+ * This document provides information about available endpoints, authentication
+ * methods, and other capabilities of the Market API.
+ */
+interface DiscoveryDocument {
+    /** URL to the API documentation */
+    api_documentation_url?: string;
+    /** Authentication schemes supported by the API */
+    authentication?: {
+        /** List of supported authentication methods */
+        schemes_supported: Array<'none' | 'apiKey' | 'oauth2'>;
+    };
+    /** API issuer identifier (typically the base domain) */
+    issuer: string;
+    /** Template for constructing manifest endpoint URLs */
+    manifest_endpoint_template: string | Record<string, string>;
+    /** Version of the market index schema */
+    market_index_schema_version: number;
+    /** URL to the privacy policy */
+    policy_url?: string;
+    /** Mapping of resource types to their endpoint paths */
+    resource_endpoints: Record<string, string>;
+    /** List of resource types available in the marketplace */
+    resource_types_supported: string[];
+    /** List of response types supported by the API */
+    response_types_supported: string[];
+    /** List of locales supported for content localization */
+    support_locales: string[];
+    /** URL to the terms of service */
+    terms_of_service_url?: string;
+}
+/**
+ * SDK Configuration Options
+ *
+ * Options for configuring the behavior of the Market SDK.
+ */
+interface MarketSDKOptions {
+    /** API key for authentication */
+    apiKey?: string;
+    /** Base URL for the Market API */
+    baseURL?: string;
+    /** Default locale to use for localized content */
+    defaultLocale?: string;
+}
+
+/**
+ * Category with count information
+ * Represents a plugin category and the number of plugins in that category.
+ */
+interface CategoryItem {
+    /** Category name */
+    category: string;
+    /** Number of plugins in this category */
+    count: number;
+}
+/**
+ * Plugin item in the marketplace
+ * Represents a plugin as displayed in the marketplace listing.
+ */
+interface PluginItem {
+    /** Authentication requirements for using the plugin */
+    authRequirement?: string;
+    /** Author or organization name */
+    author?: string;
+    /** Plugin capabilities */
+    capabilities: {
+        /** Whether the plugin provides custom prompts */
+        prompts: boolean;
+        /** Whether the plugin provides resources (assets) */
+        resources: boolean;
+        /** Whether the plugin provides tools (functions) */
+        tools: boolean;
+    };
+    /** Category for classification */
+    category?: string;
+    /** Number of comments on this plugin */
+    commentCount?: number;
+    /** Compatibility information for different platforms/versions */
+    compatibility?: PluginCompatibility;
+    /** Connection type for communicating with the plugin */
+    connectionType?: ConnectionType;
+    /** Creation timestamp (ISO 8601 format) */
+    createdAt: string;
+    /** Short description of the plugin */
+    description: string;
+    /** URL to the plugin's homepage or documentation */
+    homepage?: string;
+    /** Icon URL or emoji */
+    icon?: string;
+    /** Unique identifier for the plugin */
+    identifier: string;
+    /** Number of installations */
+    installCount?: number;
+    /** Whether the plugin can be installed */
+    isInstallable?: boolean;
+    /** Whether this is the latest version */
+    isLatest: boolean;
+    /** Whether this plugin has been validated */
+    isValidated?: boolean;
+    /** URL to the manifest file */
+    manifestUrl?: string;
+    /** Manifest schema version */
+    manifestVersion: string;
+    /** Display name of the plugin */
+    name: string;
+    /** Number of prompts provided by this plugin */
+    promptsCount?: number;
+    /** Average rating (typically 1-5 scale) */
+    ratingAverage?: number;
+    /** Number of ratings received */
+    ratingCount?: number;
+    /** Number of resources provided by this plugin */
+    resourcesCount?: number;
+    /** Tags for filtering and discovery */
+    tags?: string[];
+    /** Number of tools provided by this plugin */
+    toolsCount?: number;
+    /** Version string (e.g., "1.0.0") */
+    version: string;
+}
+/**
+ * Response structure for plugin listing endpoints
+ * Contains both the plugin items and pagination/filtering metadata.
+ */
+interface PluginListResponse {
+    /** Available categories for filtering */
+    categories: string[];
+    /** Current page number (1-based) */
+    currentPage: number;
+    /** Array of plugin items for the current page */
+    items: PluginItem[];
+    /** Number of items per page */
+    pageSize: number;
+    /** Available tags for filtering */
+    tags: string[];
+    /** Total number of items across all pages */
+    totalCount: number;
+    /** Total number of pages */
+    totalPages: number;
+}
+/**
+ * Query parameters for plugin listing
+ * Used to filter, sort, and paginate plugin results.
+ */
+interface PluginQueryParams {
+    /** Filter by category */
+    category?: string;
+    /** Locale for localized content */
+    locale?: string;
+    /** Sort direction */
+    order?: 'asc' | 'desc';
+    /** Page number (1-based) */
+    page?: number;
+    /** Number of items per page */
+    pageSize?: number;
+    /** Search query string */
+    q?: string;
+    /** Field to sort by */
+    sort?: 'installCount' | 'createdAt' | 'updatedAt' | 'ratingAverage';
+    /** Filter by tags (comma-separated) */
+    tags?: string;
 }
 
 /**
- * 基础 SDK 类
- * 提供共享的请求逻辑和认证功能
+ * Base SDK class
+ *
+ * Provides shared request handling and authentication functionality that is used
+ * by both the Market SDK and Admin SDK. This class handles the common concerns:
+ * - API endpoint configuration
+ * - Authentication header management
+ * - HTTP request handling
+ * - Error handling
+ * - Query string building
  */
 declare class BaseSDK {
+    /** Base API URL */
     protected baseUrl: string;
+    /** Default locale for requests that require localization */
     protected defaultLocale: string;
+    /** HTTP headers to include with all requests */
     protected headers: Record<string, string>;
     /**
-     * 创建基础 SDK 实例
-     * @param options SDK 配置选项
-     * @param sharedHeaders 共享的 headers 对象（可选）
+     * Creates a new BaseSDK instance
+     *
+     * @param options - Configuration options for the SDK
+     * @param sharedHeaders - Optional shared headers object for reuse across services
      */
     constructor(options?: MarketSDKOptions, sharedHeaders?: Record<string, string>);
     /**
-     * 发送请求并处理响应
-     * @param url 请求 URL
-     * @param options fetch 选项
-     * @returns 响应数据
+     * Sends an HTTP request to the API and handles the response
+     *
+     * @param url - Request URL path (will be appended to baseUrl)
+     * @param options - Fetch API request options
+     * @returns Promise resolving to the parsed JSON response
+     * @throws Error if the request fails
      */
     protected request<T>(url: string, options?: RequestInit): Promise<T>;
     /**
-     * 构建查询字符串
-     * @param params 查询参数
-     * @returns 查询字符串
+     * Builds a URL query string from a parameters object
+     *
+     * @param params - Object containing query parameters
+     * @returns Formatted query string (including leading ? if params exist)
      */
     protected buildQueryString(params: Record<string, any>): string;
     /**
-     * 设置认证令牌
-     * @param token 认证令牌
+     * Sets an authentication token for API requests
+     *
+     * @param token - API authentication token
      */
     setAuthToken(token: string): void;
     /**
-     * 清除认证令牌
+     * Clears the authentication token
      */
     clearAuthToken(): void;
 }
 
 /**
- * 插件服务
- * 处理插件相关功能
- */
-declare class PluginsService extends BaseSDK {
-    /**
-     * 创建插件服务实例
-     * @param options SDK 配置选项
-     * @param sharedHeaders 共享的 headers 对象（可选）
-     */
-    constructor(options?: MarketSDKOptions, sharedHeaders?: Record<string, string>);
-    /**
-     * 获取插件列表
-     * @param params 查询参数
-     * @returns 插件列表响应
-     */
-    getPluginList(params?: PluginQueryParams): Promise<PluginListResponse>;
-    /**
-     * 获取插件清单
-     * @param identifier 插件标识符
-     * @param locale 语言
-     * @param version 版本
-     * @returns 插件清单
-     */
-    getPluginManifest(identifier: string, locale?: string, version?: string): Promise<PluginManifest>;
-}
-
-/**
- * LobeHub Market SDK Client
- * 采用组合模式组合各个领域服务
- */
-declare class MarketSDK extends BaseSDK {
-    /**
-     * 插件服务
-     */
-    readonly plugins: PluginsService;
-    /**
-     * 发现服务
-     */
-    private readonly discovery;
-    /**
-     * Create MarketSDK instance
-     * @param options SDK configuration options
-     */
-    constructor(options?: MarketSDKOptions);
-    /**
-     * Get market service discovery document
-     * @returns Service discovery document
-     */
-    getDiscoveryDocument(): Promise<DiscoveryDocument>;
-}
-
-/**
- * 插件管理服务
- * 处理插件相关的管理功能
+ * Plugin Management Service
+ *
+ * Provides administrative functionality for managing plugins in the marketplace.
+ * This service handles CRUD operations for plugins, plugin versions, and deployment options.
  */
 declare class PluginService extends BaseSDK {
     /**
-     * 创建插件管理服务实例
-     * @param options SDK 配置选项
-     * @param sharedHeaders 共享的 headers 对象（可选）
+     * Creates a new PluginService instance
+     *
+     * @param options - Configuration options for the SDK
+     * @param sharedHeaders - Optional shared headers object for reuse across services
      */
     constructor(options?: MarketSDKOptions, sharedHeaders?: Record<string, string>);
     /**
-     * 导入插件清单（需要管理员权限）
-     * @param manifests 插件清单数组
-     * @param ownerId 所有者 ID
-     * @returns 导入结果
+     * Imports plugin manifests (requires admin privileges)
+     *
+     * Allows batch importing of plugin manifests into the marketplace.
+     *
+     * @param manifests - Array of plugin manifests to import
+     * @param ownerId - Optional owner ID to associate with the imported plugins
+     * @returns Promise resolving to the import results with counts of success and failure
      */
     importManifests(manifests: PluginManifest[], ownerId?: number): Promise<{
-        success: number;
         failed: number;
+        success: number;
     }>;
     /**
-     * 获取插件列表
-     * @param params 查询参数
-     * @returns 插件列表响应
+     * Retrieves a list of plugins with admin details
+     *
+     * Supports filtering, pagination, and sorting of results.
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Promise resolving to the plugin list response with admin details
      */
     getPlugins(params?: AdminListQueryParams): Promise<AdminListResponse<AdminPluginItem>>;
     /**
-     * 获取单个插件
-     * @param id 插件 ID
-     * @returns 插件详情
+     * Retrieves a single plugin with full admin details
+     *
+     * @param id - Plugin ID or identifier
+     * @returns Promise resolving to the detailed plugin information with version history
      */
-    getPlugin(id: number | string): Promise<AdminPluginItem & {
-        versions: PluginVersion[];
-    }>;
+    getPlugin(id: number | string): Promise<AdminPluginItemDetail>;
     /**
-     * 更新插件信息
-     * @param id 插件 ID
-     * @param data 插件更新数据
-     * @returns 更新后的插件
+     * Updates plugin information
+     *
+     * @param id - Plugin ID
+     * @param data - Plugin update data containing fields to update
+     * @returns Promise resolving to the updated plugin
      */
     updatePlugin(id: number, data: PluginUpdateParams): Promise<AdminPluginItem>;
     /**
-     * 更新插件状态
-     * @param id 插件 ID
-     * @param status 新状态
-     * @returns 成功响应
+     * Updates plugin publication status
+     *
+     * @param id - Plugin ID
+     * @param status - New status to set
+     * @returns Promise resolving to success response
      */
     updatePluginStatus(id: number, status: 'published' | 'draft' | 'review' | 'rejected'): Promise<{
-        success: boolean;
         message: string;
+        success: boolean;
     }>;
     /**
-     * 删除插件
-     * @param id 插件 ID
-     * @returns 成功响应
+     * Deletes a plugin
+     *
+     * @param id - Plugin ID
+     * @returns Promise resolving to success response
      */
     deletePlugin(id: number): Promise<{
-        success: boolean;
         message: string;
+        success: boolean;
     }>;
     /**
-     * 获取插件版本列表
-     * @param pluginId 插件 ID
-     * @returns 插件版本列表
+     * Retrieves the version history for a plugin
+     *
+     * @param pluginId - Plugin ID
+     * @returns Promise resolving to an array of plugin versions
      */
     getPluginVersions(pluginId: number): Promise<PluginVersion[]>;
     /**
-     * 获取单个插件版本
-     * @param pluginId 插件 ID
-     * @param versionId 版本 ID
-     * @returns 插件版本
+     * Retrieves a specific plugin version
+     *
+     * @param pluginId - Plugin ID
+     * @param versionId - Version ID
+     * @returns Promise resolving to the plugin version details
      */
     getPluginVersion(pluginId: number, versionId: number): Promise<PluginVersion>;
     /**
-     * 创建插件版本
-     * @param pluginId 插件 ID
-     * @param data 版本创建数据
-     * @returns 创建的版本
+     * Creates a new plugin version
+     *
+     * @param pluginId - Plugin ID
+     * @param data - Version creation data including manifest and version string
+     * @returns Promise resolving to the created plugin version
      */
     createPluginVersion(pluginId: number, data: PluginVersionCreateParams): Promise<PluginVersion>;
     /**
-     * 更新插件版本
-     * @param pluginId 插件 ID
-     * @param versionId 版本 ID
-     * @param data 版本更新数据
-     * @returns 更新后的版本
+     * Updates a plugin version
+     *
+     * @param pluginId - Plugin ID
+     * @param versionId - Version ID
+     * @param data - Version update data
+     * @returns Promise resolving to the updated plugin version
      */
     updatePluginVersion(pluginId: number, versionId: number, data: PluginVersionUpdateParams): Promise<PluginVersion>;
     /**
-     * 删除插件版本
-     * @param pluginId 插件 ID
-     * @param versionId 版本 ID
-     * @returns 成功响应
+     * Deletes a plugin version
+     *
+     * @param pluginId - Plugin ID
+     * @param versionId - Version ID
+     * @returns Promise resolving to success response
      */
     deletePluginVersion(pluginId: number, versionId: number): Promise<{
-        success: boolean;
         message: string;
+        success: boolean;
     }>;
     /**
-     * 设置插件版本为最新版本
-     * @param pluginId 插件 ID
-     * @param versionId 版本 ID
-     * @returns 成功响应
+     * Sets a specific version as the latest version of a plugin
+     *
+     * @param pluginId - Plugin ID
+     * @param versionId - Version ID to set as latest
+     * @returns Promise resolving to success response
      */
     setPluginVersionAsLatest(pluginId: number, versionId: number): Promise<{
-        success: boolean;
         message: string;
+        success: boolean;
     }>;
     /**
-     * 更新插件可见性
-     * @param id 插件 ID
-     * @param visibility 新的可见性状态
-     * @returns 成功响应
+     * Updates plugin visibility
+     *
+     * @param id - Plugin ID
+     * @param visibility - New visibility setting
+     * @returns Promise resolving to success response
      */
     updatePluginVisibility(id: number, visibility: 'public' | 'private' | 'unlisted'): Promise<{
-        success: boolean;
         message: string;
+        success: boolean;
     }>;
     /**
-     * 批量更新插件状态
-     * @param ids 插件 ID 数组
-     * @param status 新的状态
-     * @returns 成功响应
+     * Updates status for multiple plugins in a single operation
+     *
+     * @param ids - Array of plugin IDs to update
+     * @param status - New status to set for all specified plugins
+     * @returns Promise resolving to success response
      */
     batchUpdatePluginStatus(ids: number[], status: 'published' | 'draft' | 'review' | 'rejected'): Promise<{
-        success: boolean;
         message: string;
+        success: boolean;
     }>;
     /**
-     * 批量删除插件
-     * @param ids 插件 ID 数组
-     * @returns 成功响应
+     * Deletes multiple plugins in a single operation
+     *
+     * @param ids - Array of plugin IDs to delete
+     * @returns Promise resolving to success response
      */
     batchDeletePlugins(ids: number[]): Promise<{
-        success: boolean;
         message: string;
+        success: boolean;
     }>;
     /**
-     * 获取插件版本详情
-     * @param pluginId 插件 ID
-     * @param versionId 版本 ID
-     * @returns 版本详情
+     * Retrieves detailed information about a plugin version including deployment options
+     *
+     * @param pluginId - Plugin ID
+     * @param versionId - Version ID
+     * @returns Promise resolving to version details with deployment options
      */
     getPluginVersionDetails(pluginId: number, versionId: number): Promise<PluginVersion & {
         deploymentOptions: any;
     }>;
     /**
-     * 更新插件版本信息
-     * @param pluginId 插件 ID
-     * @param versionId 版本 ID
-     * @param data 版本更新数据
-     * @returns 更新后的版本
+     * Updates detailed information for a plugin version
+     *
+     * @param pluginId - Plugin ID
+     * @param versionId - Version ID
+     * @param data - Detailed version update data including metadata and capabilities
+     * @returns Promise resolving to the updated plugin version
      */
     updatePluginVersionDetails(pluginId: number, versionId: number, data: {
         author?: string;
         authorUrl?: string;
-        name?: string;
-        description?: string;
-        tags?: string[];
-        icon?: string;
-        category?: string;
-        capabilitiesTools?: boolean;
         capabilitiesPrompts?: boolean;
         capabilitiesResources?: boolean;
-        tools?: any;
-        resources?: any;
-        prompts?: any;
+        capabilitiesTools?: boolean;
+        category?: string;
+        description?: string;
+        icon?: string;
         isValidated?: boolean;
         meta?: Record<string, any>;
+        name?: string;
+        prompts?: any;
+        resources?: any;
+        tags?: string[];
+        tools?: any;
     }): Promise<PluginVersion>;
     /**
-     * 获取插件版本的部署选项列表
-     * @param pluginId 插件 ID
-     * @param versionId 版本 ID
-     * @returns 部署选项列表
+     * Retrieves deployment options for a specific plugin version
+     *
+     * @param pluginId - Plugin ID
+     * @param versionId - Version ID
+     * @returns Promise resolving to an array of deployment options
      */
     getDeploymentOptions(pluginId: number, versionId: number): Promise<AdminDeploymentOption[]>;
     /**
-     * 创建部署选项
-     * @param pluginId 插件 ID
-     * @param versionId 版本 ID
-     * @param data 部署选项数据
-     * @returns 创建的部署选项
+     * Creates a new deployment option for a plugin version
+     *
+     * @param pluginId - Plugin ID
+     * @param versionId - Version ID
+     * @param data - Deployment option configuration data
+     * @returns Promise resolving to the created deployment option
      */
     createDeploymentOption(pluginId: number, versionId: number, data: {
-        installationMethod: string;
-        installationDetails: Record<string, any>;
-        connectionType: string;
-        connectionCommand?: string;
         connectionArgs?: string[];
-        isRecommended?: boolean;
+        connectionCommand?: string;
+        connectionType: string;
         description?: string;
+        installationDetails?: InstallationDetails;
+        installationMethod: string;
+        isRecommended?: boolean;
     }): Promise<AdminDeploymentOption>;
     /**
-     * 更新部署选项
-     * @param pluginId 插件 ID
-     * @param versionId 版本 ID
-     * @param optionId 部署选项 ID
-     * @param data 部署选项更新数据
-     * @returns 更新后的部署选项
+     * Updates an existing deployment option
+     *
+     * @param pluginId - Plugin ID
+     * @param versionId - Version ID
+     * @param optionId - Deployment option ID
+     * @param data - Updated deployment option configuration
+     * @returns Promise resolving to the updated deployment option
      */
     updateDeploymentOption(pluginId: number, versionId: number, optionId: number, data: {
-        installationMethod?: string;
-        installationDetails?: Record<string, any>;
-        connectionType?: string;
-        connectionCommand?: string;
         connectionArgs?: string[];
-        isRecommended?: boolean;
+        connectionCommand?: string;
+        connectionType?: string;
         description?: string;
+        installationDetails?: Record<string, any>;
+        installationMethod?: string;
+        isRecommended?: boolean;
     }): Promise<AdminDeploymentOption>;
     /**
-     * 删除部署选项
-     * @param pluginId 插件 ID
-     * @param versionId 版本 ID
-     * @param optionId 部署选项 ID
-     * @returns 成功响应
+     * Deletes a deployment option
+     *
+     * @param pluginId - Plugin ID
+     * @param versionId - Version ID
+     * @param optionId - Deployment option ID
+     * @returns Promise resolving to success response
      */
     deleteDeploymentOption(pluginId: number, versionId: number, optionId: number): Promise<{
-        success: boolean;
         message: string;
+        success: boolean;
     }>;
     /**
-     * 获取部署选项的系统依赖
-     * @param pluginId 插件 ID
-     * @param versionId 版本 ID
-     * @param optionId 部署选项 ID
-     * @returns 系统依赖列表
+     * Retrieves system dependencies for a deployment option
+     *
+     * @param pluginId - Plugin ID
+     * @param versionId - Version ID
+     * @param optionId - Deployment option ID
+     * @returns Promise resolving to an array of system dependencies
      */
     getDeploymentOptionSystemDependencies(pluginId: number, versionId: number, optionId: number): Promise<SystemDependency[]>;
 }
 
 /**
- * 系统依赖管理服务
+ * System Dependency Management Service
+ *
+ * Provides administrative functionality for managing system dependencies
+ * required by plugins. This service handles creating, updating, deleting,
+ * and listing system dependencies that plugins may require.
  */
 declare class SystemDependencyService extends BaseSDK {
     /**
-     * 创建系统依赖管理服务实例
-     * @param options SDK 配置选项
-     * @param sharedHeaders 共享的 headers 对象（可选）
+     * Creates a new SystemDependencyService instance
+     *
+     * @param options - Configuration options for the SDK
+     * @param sharedHeaders - Optional shared headers object for reuse across services
      */
     constructor(options?: MarketSDKOptions, sharedHeaders?: Record<string, string>);
     /**
-     * 获取所有系统依赖项
-     * @returns 系统依赖项列表
+     * Retrieves all system dependencies
+     *
+     * Gets a list of all defined system dependencies that plugins may require.
+     *
+     * @returns Promise resolving to an array of system dependencies
      */
     getSystemDependencies(): Promise<SystemDependency[]>;
     /**
-     * 获取特定系统依赖项
-     * @param id 依赖项 ID
-     * @returns 系统依赖项
+     * Retrieves a specific system dependency by ID
+     *
+     * @param id - System dependency ID
+     * @returns Promise resolving to the system dependency details
      */
     getSystemDependency(id: number): Promise<SystemDependency>;
     /**
-     * 创建系统依赖项
-     * @param data 依赖项创建数据
-     * @returns 创建的依赖项
+     * Creates a new system dependency
+     *
+     * @param data - System dependency creation data
+     * @returns Promise resolving to the created system dependency
      */
     createSystemDependency(data: Omit<SystemDependency, 'id'>): Promise<SystemDependency>;
     /**
-     * 更新系统依赖项
-     * @param id 依赖项 ID
-     * @param data 依赖项更新数据
-     * @returns 更新后的依赖项
+     * Updates an existing system dependency
+     *
+     * @param id - System dependency ID
+     * @param data - System dependency update data
+     * @returns Promise resolving to the updated system dependency
      */
     updateSystemDependency(id: number, data: Partial<SystemDependency>): Promise<SystemDependency>;
     /**
-     * 删除系统依赖项
-     * @param id 依赖项 ID
-     * @returns 成功响应
+     * Deletes a system dependency
+     *
+     * @param id - System dependency ID
+     * @returns Promise resolving to success response
      */
     deleteSystemDependency(id: number): Promise<{
-        success: boolean;
         message: string;
+        success: boolean;
     }>;
 }
 
+/**
+ * Settings entity representing a system setting
+ */
 interface Settings {
+    /** Creation timestamp (ISO 8601 format) */
+    createdAt: string;
+    /** Optional description of the setting's purpose */
+    description?: string;
+    /** Unique identifier for the setting */
     id: number;
+    /** Setting key name used for retrieving the setting */
     key: string;
-    value: string;
-    description?: string;
-    createdAt: string;
+    /** Last update timestamp (ISO 8601 format) */
     updatedAt: string;
+    /** Setting value (stored as string) */
+    value: string;
 }
+/**
+ * Configuration for enabled resource types
+ */
 interface EnabledResources {
-    plugins: boolean;
+    /** Whether agent resources are enabled */
     agents: boolean;
+    /** Whether plugin resources are enabled */
+    plugins: boolean;
 }
+/**
+ * Authentication configuration
+ */
 interface AuthenticationConfig {
+    /** Whether authentication is required */
     enabled: boolean;
+    /** Supported authentication schemes */
     schemes: string[];
 }
+/**
+ * Documentation URL configuration
+ */
 interface DocumentationConfig {
+    /** URL to API documentation */
     apiUrl?: string;
+    /** URL to privacy policy */
     policyUrl?: string;
+    /** URL to terms of service */
     termsOfServiceUrl?: string;
 }
+/**
+ * Map of all system settings with typed properties
+ */
 interface SettingsMap {
-    baseURL: string;
-    enabledResources: EnabledResources;
+    /** Additional settings (dynamically added) */
+    [key: string]: any;
+    /** Authentication configuration */
     authentication: AuthenticationConfig;
+    /** Base URL for the marketplace */
+    baseURL: string;
+    /** Documentation URL configuration */
     documentation: DocumentationConfig;
+    /** Configuration for enabled resource types */
+    enabledResources: EnabledResources;
+    /** Supported locales */
     locales: string[];
-    [key: string]: any;
 }
+/**
+ * Parameters for creating a new setting
+ */
 interface CreateSettingsParams {
+    /** Optional description of the setting's purpose */
+    description?: string;
+    /** Setting key name */
     key: string;
+    /** Setting value (will be stored as string) */
     value: string;
-    description?: string;
 }
+/**
+ * Parameters for updating an existing setting
+ */
 interface UpdateSettingsParams {
-    value: string;
+    /** Optional new description */
     description?: string;
+    /** New setting value */
+    value: string;
 }
 /**
- * 系统设置管理服务
- * 处理系统设置相关的管理功能
+ * Settings Management Service
+ *
+ * Provides administrative functionality for managing system settings.
+ * This service handles getting, creating, updating, and deleting
+ * configuration settings for the marketplace.
  */
 declare class SettingsService extends BaseSDK {
     /**
-     * 获取设置列表
-     * @param params 查询参数
-     * @returns 设置键值对对象
+     * Retrieves all system settings
+     *
+     * Returns a consolidated map of all settings with typed values
+     * for known setting keys.
+     *
+     * @returns Promise resolving to the settings map
      */
     getSettings(): Promise<SettingsMap>;
     /**
-     * 获取单个设置
-     * @param key 设置键名
-     * @returns 设置详情
+     * Retrieves a specific setting by key
+     *
+     * @param key - Setting key name
+     * @returns Promise resolving to the setting details
      */
     getSettingByKey(key: string): Promise<{
         data: Settings;
     }>;
     /**
-     * 创建设置
-     * @param data 设置数据
-     * @returns 创建的设置
+     * Creates a new system setting
+     *
+     * @param data - Setting creation parameters
+     * @returns Promise resolving to the created setting
      */
     createSetting(data: CreateSettingsParams): Promise<{
         data: Settings;
     }>;
     /**
-     * 更新设置
-     * @param key 设置键名
-     * @param data 更新数据
-     * @returns 更新后的设置
+     * Updates an existing setting
+     *
+     * @param key - Setting key name
+     * @param data - Setting update parameters
+     * @returns Promise resolving to the updated setting
      */
     updateSetting(key: string, data: UpdateSettingsParams): Promise<{
         data: Settings;
     }>;
     /**
-     * 删除设置
-     * @param key 设置键名
-     * @returns 删除结果
+     * Deletes a setting
+     *
+     * @param key - Setting key name
+     * @returns Promise resolving to success message
      */
     deleteSetting(key: string): Promise<{
         message: string;
     }>;
 }
 
+/**
+ * Review entity representing a plugin review
+ */
 interface Review {
+    /** Optional comment providing feedback */
+    comment?: string;
+    /** Creation timestamp (ISO 8601 format) */
+    createdAt: string;
+    /** Unique identifier for the review */
     id: number;
+    /** ID of the plugin being reviewed */
     pluginId: number;
-    status: ReviewStatus;
-    comment?: string;
+    /** ID of the reviewer (if available) */
     reviewerId?: number;
-    createdAt: string;
+    /** Current status of the review */
+    status: ReviewStatus;
+    /** Last update timestamp (ISO 8601 format) */
     updatedAt: string;
 }
+/**
+ * Extended review information with related entities
+ */
 interface PluginReviewWithRelations extends Review {
+    /** Related plugin information */
     plugin?: any;
+    /** Related version information */
     version?: any;
 }
+/**
+ * Parameters for updating a review
+ */
 interface UpdateReviewParams {
-    status: ReviewStatus;
+    /** Optional comment or feedback */
     comment?: string;
+    /** New status to set for the review */
+    status: ReviewStatus;
 }
 /**
- * 审核管理服务
- * 处理插件审核相关的管理功能
+ * Review Management Service
+ *
+ * Provides administrative functionality for managing plugin reviews.
+ * This service handles listing, fetching, and updating review statuses
+ * for plugins in the marketplace.
  */
 declare class ReviewService extends BaseSDK {
     /**
-     * 创建审核管理服务实例
-     * @param options SDK 配置选项
-     * @param sharedHeaders 共享的 headers 对象（可选）
+     * Creates a new ReviewService instance
+     *
+     * @param options - Configuration options for the SDK
+     * @param sharedHeaders - Optional shared headers object for reuse across services
      */
     constructor(options?: MarketSDKOptions, sharedHeaders?: Record<string, string>);
     /**
-     * 获取审核列表
-     * @param params 查询参数
-     * @returns 审核列表响应
+     * Retrieves a list of reviews with filtering options
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Promise resolving to the review list response
      */
     getReviews(params?: AdminListQueryParams): Promise<AdminListResponse<PluginReviewWithRelations>>;
     /**
-     * 获取审核详情
-     * @param id 审核 ID
-     * @returns 审核详情
+     * Retrieves a specific review by ID
+     *
+     * @param id - Review ID
+     * @returns Promise resolving to the review details
      */
     getReviewById(id: number): Promise<Review>;
     /**
-     * 更新审核状态
-     * @param id 审核 ID
-     * @param data 更新数据
-     * @returns 更新后的审核信息
+     * Updates a review's status and comment
+     *
+     * @param id - Review ID
+     * @param data - Update parameters containing new status and optional comment
+     * @returns Promise resolving to the updated review
      */
     updateReview(id: number, data: UpdateReviewParams): Promise<Review>;
     /**
-     * 获取插件的审核历史
-     * @param pluginId 插件 ID
-     * @returns 审核历史列表
+     * Retrieves the review history for a specific plugin
+     *
+     * @param pluginId - Plugin ID
+     * @returns Promise resolving to an array of reviews for the plugin
      */
     getPluginReviews(pluginId: number): Promise<{
         data: Review[];
@@ -677,31 +890,122 @@ declare class ReviewService extends BaseSDK {
 }
 
 /**
- * LobeHub 市场管理 SDK 客户端
- * 专门用于管理市场的管理功能
+ * LobeHub Market Admin SDK Client
+ *
+ * Client for accessing administrative functionality of the LobeHub Marketplace.
+ * This SDK provides privileged operations for managing plugins, reviews,
+ * system settings, and dependencies. It requires admin-level authentication.
  */
 declare class MarketAdmin extends BaseSDK {
     /**
-     * 插件管理服务
+     * Plugin management service
+     * Provides methods for creating, updating, and managing plugins
      */
     readonly plugins: PluginService;
     /**
-     * 审核管理服务
+     * Review management service
+     * Provides methods for moderating and managing user reviews
      */
     readonly reviews: ReviewService;
     /**
-     * 系统设置管理服务
+     * System settings management service
+     * Provides methods for configuring marketplace settings
      */
     readonly settings: SettingsService;
     /**
-     * 系统依赖管理服务
+     * System dependency management service
+     * Provides methods for managing system dependencies required by plugins
      */
     readonly dependencies: SystemDependencyService;
     /**
-     * 创建 MarketAdmin 实例
-     * @param options SDK 配置选项
+     * Creates a new MarketAdmin instance
+     *
+     * @param options - Configuration options for the SDK
+     */
+    constructor(options?: MarketSDKOptions);
+}
+
+/**
+ * Plugins Service
+ *
+ * Provides access to plugin-related functionality in the LobeHub Marketplace.
+ * This service handles listing, searching, and retrieving detailed information
+ * about plugins available in the marketplace.
+ */
+declare class PluginsService extends BaseSDK {
+    /**
+     * Creates a new PluginsService instance
+     *
+     * @param options - Configuration options for the SDK
+     * @param sharedHeaders - Optional shared headers object for reuse across services
+     */
+    constructor(options?: MarketSDKOptions, sharedHeaders?: Record<string, string>);
+    /**
+     * Retrieves a list of plugins from the marketplace
+     *
+     * Supports filtering, pagination, and localization of results.
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Promise resolving to the plugin list response containing items and pagination info
+     */
+    getPluginList(params?: PluginQueryParams): Promise<PluginListResponse>;
+    /**
+     * Retrieves all plugin categories and their counts
+     *
+     * Returns a list of categories along with the number of plugins in each category.
+     * Useful for building category filters in a UI.
+     *
+     * @returns Promise resolving to an array of category items with counts
+     */
+    getCategories(): Promise<CategoryItem[]>;
+    /**
+     * Retrieves the manifest for a specific plugin
+     *
+     * The manifest contains detailed information about a plugin, including
+     * its capabilities, tools, prompts, and resources.
+     *
+     * @param identifier - Unique identifier of the plugin
+     * @param locale - Optional locale for localized content (defaults to SDK default locale)
+     * @param version - Optional specific version to retrieve (defaults to latest)
+     * @returns Promise resolving to the plugin manifest
+     */
+    getPluginManifest(identifier: string, locale?: string, version?: string): Promise<PluginManifest>;
+}
+
+/**
+ * LobeHub Market SDK Client
+ *
+ * Main client for accessing the LobeHub Marketplace API.
+ * This class provides access to marketplace resources like plugins, agents,
+ * and service discovery information. It follows a composition pattern
+ * by combining specialized domain services.
+ */
+declare class MarketSDK extends BaseSDK {
+    /**
+     * Plugins service for accessing plugin-related functionality
+     * Provides methods to list, search, and retrieve plugin information
+     */
+    readonly plugins: PluginsService;
+    /**
+     * Discovery service for retrieving API service information
+     * Used to get information about available endpoints and services
+     */
+    private readonly discovery;
+    /**
+     * Creates a new MarketSDK instance
+     *
+     * @param options - Configuration options for the SDK
      */
     constructor(options?: MarketSDKOptions);
+    /**
+     * Retrieves the service discovery document
+     *
+     * The discovery document provides information about available API endpoints,
+     * versions, and capabilities of the Market API.
+     *
+     * @returns Promise resolving to the service discovery document
+     */
+    getDiscoveryDocument(): Promise<DiscoveryDocument>;
 }
 
-export { type AdminListQueryParams, type AdminListResponse, type AdminPluginParams, type DiscoveryDocument, MarketAdmin, MarketSDK, type MarketSDKOptions, type PluginItem, type PluginListResponse, type PluginQueryParams, type PluginUpdateParams, type PluginVersion, type PluginVersionCreateParams, type PluginVersionUpdateParams, type ReviewStatus, ReviewStatusEnumSchema, StatusEnumSchema, VisibilityEnumSchema };
+export { type AdminListQueryParams, type AdminListResponse, type AdminPluginParams, type CategoryItem, type DiscoveryDocument, MarketAdmin, MarketSDK, type MarketSDKOptions, type PluginItem, type PluginListResponse, type PluginQueryParams, type PluginUpdateParams, type PluginVersionCreateParams, type PluginVersionUpdateParams, type ReviewStatus, ReviewStatusEnumSchema, StatusEnumSchema, VisibilityEnumSchema };