@lobehub/market-sdk 0.0.28 → 0.0.29

package/README.md

@@ -1,172 +1,270 @@
-# @lobehub/market-sdk
+# LobeHub Market JavaScript SDK
 
-LobeHub Market 的 JavaScript SDK，提供对插件市场 API 的简单访问。
+[![NPM version](https://img.shields.io/npm/v/@lobehub/market-sdk.svg?style=flat)](https://npmjs.org/package/@lobehub/market-sdk)
+[![NPM downloads](https://img.shields.io/npm/dm/@lobehub/market-sdk.svg?style=flat)](https://npmjs.org/package/@lobehub/market-sdk)
 
-## 特性
+A JavaScript SDK for accessing the LobeHub Market API, providing easy integration with the LobeHub ecosystem.
 
-- 使用原生 `fetch` API，无外部依赖
-- 支持 TypeScript，提供完整类型定义
-- 简单易用的 API 设计
-- 支持 ESM 模块
+## Features
 
-## 安装
+- 🚀 **Easy Integration**: Simple API for accessing LobeHub Marketplace resources
+- 🔌 **Plugin Support**: Browse, search, and fetch plugin manifests
+- 🔒 **Authentication**: Secure API access with token-based authentication
+- 🧩 **Modular Architecture**: Logically separated services for different API domains
+- 🌐 **Localization**: Built-in support for localized content
+- 🔍 **Discovery**: Automatic service discovery for API capabilities
+- 📊 **Admin Tools**: Comprehensive admin APIs for marketplace management
+
+## Installation
 
 ```bash
+# Using npm
 npm install @lobehub/market-sdk
+
+# Using yarn
+yarn add @lobehub/market-sdk
+
+# Using pnpm
+pnpm add @lobehub/market-sdk
 ```
 
-## 用法
+## Package Structure
 
-### 基本使用
+```
+src/
+├── market/            - Market SDK implementation
+│   ├── services/      - Market services
+│   │   ├── PluginsService.ts    - Plugin-related operations
+│   │   └── DiscoveryService.ts  - API discovery
+│   └── market-sdk.ts  - Main SDK class
+├── admin/             - Admin SDK implementation
+│   ├── services/      - Admin services
+│   │   ├── PluginService.ts     - Plugin management
+│   │   ├── ReviewService.ts     - Review management
+│   │   ├── SettingsService.ts   - Settings management
+│   │   └── SystemDependencyService.ts - Dependencies management
+│   └── MarketAdmin.ts - Admin SDK class
+├── core/              - Core utilities and base classes
+├── types/             - TypeScript type definitions
+└── index.ts           - Main entry point
+```
+
+## Usage
+
+### Market SDK
 
 ```typescript
 import { MarketSDK } from '@lobehub/market-sdk';
 
-// 创建 SDK 实例
+// Create a client instance
 const market = new MarketSDK({
-  // 可选配置
-  baseUrl: 'https://market.lobehub.com/api', // 默认值
-  defaultLocale: 'zh-CN', // 默认值
-});
-
-// 获取服务发现文档
-const discovery = await market.getDiscoveryDocument();
-console.log(discovery);
-
-// 获取插件列表
-const plugins = await market.getPluginList({
-  page: 1,
-  pageSize: 10,
-  category: 'tools',
-  sort: 'installCount',
-  order: 'desc',
+  // Optional: custom API base URL (defaults to https://market.lobehub.com/api)
+  baseURL: 'https://your-api-url.com/api',
+  // Optional: API key for authentication
+  apiKey: 'your-api-key',
+  // Optional: default locale for localized content
+  defaultLocale: 'en-US',
 });
-console.log(plugins);
 
-// 获取插件清单
-const manifest = await market.getPluginManifest('lobehub/web-search');
-console.log(manifest);
+// Example: Get a list of plugins
+async function getPlugins() {
+  try {
+    const result = await market.plugins.getPluginList({
+      page: 1,
+      pageSize: 10,
+      locale: 'en-US',
+      // Additional filter parameters
+    });
+
+    console.log(`Found ${result.data.items.length} plugins`);
+    console.log('Plugins:', result.data.items);
+  } catch (error) {
+    console.error('Error fetching plugins:', error);
+  }
+}
+
+// Example: Get plugin categories
+async function getCategories() {
+  try {
+    const result = await market.plugins.getCategories();
+    console.log('Categories:', result.data);
+  } catch (error) {
+    console.error('Error fetching categories:', error);
+  }
+}
+
+// Example: Get a plugin's manifest
+async function getPluginManifest(pluginId) {
+  try {
+    const result = await market.plugins.getPluginManifest({ id: pluginId });
+    console.log('Plugin manifest:', result.data);
+  } catch (error) {
+    console.error('Error fetching plugin manifest:', error);
+  }
+}
 ```
 
-### 认证
+### Admin SDK
 
-对于需要管理员权限的操作，需要提供认证令牌：
+For administrative operations, use the `MarketAdmin` class:
 
 ```typescript
-// 创建时提供 API Key
-const market = new MarketSDK({
-  apiKey: 'your-api-key',
+import { MarketAdmin } from '@lobehub/market-sdk';
+
+// Create an admin client instance
+const admin = new MarketAdmin({
+  // Required: Admin API key
+  apiKey: 'your-admin-api-key',
+  // Optional: custom API base URL
+  baseURL: 'https://your-api-url.com/api',
 });
 
-// 或者稍后设置
-market.setAuthToken('your-api-key');
-
-// 导入插件清单 (需要管理员权限)
-const result = await market.importManifests([
-  {
-    id: 'my-plugin',
-    name: 'My Plugin',
-    version: '1.0.0',
-    description: '一个示例插件',
-    // 其他清单字段...
-  },
-]);
-console.log(result);
+// Example: Create a new plugin
+async function createPlugin() {
+  try {
+    const result = await admin.plugins.createPlugin({
+      meta: {
+        title: 'My Plugin',
+        description: 'A sample plugin',
+        author: 'LobeHub',
+        homepage: 'https://github.com/lobehub/my-plugin',
+      },
+      manifest: {
+        // Plugin manifest details
+      },
+    });
+
+    console.log('Plugin created:', result.data);
+  } catch (error) {
+    console.error('Error creating plugin:', error);
+  }
+}
+
+// Example: Update plugin settings
+async function updateSettings() {
+  try {
+    const result = await admin.settings.updateSettings({
+      pluginReviewEnabled: true,
+      publishPluginEnabled: true,
+    });
+
+    console.log('Settings updated:', result.data);
+  } catch (error) {
+    console.error('Error updating settings:', error);
+  }
+}
 ```
 
-## API 参考
+## API Reference
 
-### `MarketSDK`
+### MarketSDK Services
 
-主要的 SDK 类
+#### plugins
 
-#### 构造函数
+Methods for accessing plugin resources:
 
-```typescript
-constructor(options?: MarketSDKOptions)
-```
+- `getPluginList(params)`: Get a paginated list of plugins
+
+  ```typescript
+  market.plugins.getPluginList({
+    page: 1,
+    pageSize: 10,
+    locale: 'en-US',
+    category: 'tools',
+    searchKey: 'weather',
+    tags: ['api'],
+    sort: 'downloads',
+  });
+  ```
 
-参数:
+- `getCategories()`: Get plugin categories
 
-- `options.baseUrl`: API 基础 URL，默认为 'https://market.lobehub.com/api'
-- `options.defaultLocale`: 默认语言，默认为 'zh-CN'
-- `options.apiKey`: 可选的 API 认证密钥
+  ```typescript
+  market.plugins.getCategories();
+  ```
 
-#### 方法
+- `getPluginManifest(params)`: Get a plugin's manifest
 
-##### `getDiscoveryDocument()`
+  ```typescript
+  market.plugins.getPluginManifest({ id: 'plugin-id' });
+  ```
 
-获取市场服务发现文档。
+- `getPluginDetail(params)`: Get detailed information about a plugin
+  ```typescript
+  market.plugins.getPluginDetail({ id: 'plugin-id' });
+  ```
 
-##### `getPluginList(params)`
+#### discovery
 
-获取插件列表。
+- `getDiscoveryDocument()`: Get API capability information
+  ```typescript
+  market.discovery.getDiscoveryDocument();
+  ```
 
-参数:
+### MarketAdmin Services
 
-- `params.page`: 页码，默认为 1
-- `params.pageSize`: 每页数量，默认为 20
-- `params.category`: 按分类筛选
-- `params.tags`: 按标签筛选 (逗号分隔)
-- `params.q`: 搜索关键词
-- `params.sort`: 排序字段 ('installCount', 'createdAt', 'updatedAt', 'ratingAverage')
-- `params.order`: 排序方向 ('asc' 或 'desc')
-- `params.locale`: 语言，默认为构造函数中设置的值
+#### plugins
 
-##### `getPluginManifest(identifier, locale?, version?)`
+Methods for managing plugins:
 
-获取插件清单。
+- `createPlugin(data)`: Create a new plugin
+- `updatePlugin(params, data)`: Update an existing plugin
+- `getPluginList(params)`: Get a list of plugins (admin view)
+- `getPluginDetail(params)`: Get detailed plugin information
+- `deletePlugin(params)`: Delete a plugin
+- `publishPlugin(params)`: Publish a plugin
+- `unpublishPlugin(params)`: Unpublish a plugin
+- `approvePlugin(params)`: Approve a plugin
+- `rejectPlugin(params)`: Reject a plugin
 
-参数:
+#### reviews
 
-- `identifier`: 插件标识符 (必填)
-- `locale`: 语言，可选，默认为构造函数中设置的值
-- `version`: 版本号，可选，默认获取最新版本
+Methods for managing user reviews:
 
-##### `importManifests(manifests, ownerId?)`
+- `getReviewList(params)`: Get a list of reviews
+- `createReview(data)`: Create a new review
+- `deleteReview(params)`: Delete a review
+- `approveReview(params)`: Approve a review
+- `rejectReview(params)`: Reject a review
 
-导入插件清单 (需要管理员权限)。
+#### settings
 
-参数:
+Methods for managing marketplace settings:
 
-- `manifests`: 插件清单数组
-- `ownerId`: 所有者 ID (可选)
+- `getSettings()`: Get current marketplace settings
+- `updateSettings(data)`: Update marketplace settings
 
-##### `setAuthToken(token)`
+#### dependencies
 
-设置认证令牌。
+Methods for managing system dependencies:
 
-##### `clearAuthToken()`
+- `getDependencyList(params)`: Get a list of system dependencies
+- `createDependency(data)`: Create a new system dependency
+- `updateDependency(params, data)`: Update an existing dependency
+- `deleteDependency(params)`: Delete a system dependency
 
-清除认证令牌。
+## TypeScript Support
 
-## 类型
+This SDK is written in TypeScript and provides comprehensive type definitions for all APIs. The types are automatically included when you install the package.
 
-SDK 导出以下类型:
+## Error Handling
 
-- `PluginType`
-- `ConnectionType`
-- `InstallationMethod`
-- `SystemDependency`
-- `ConnectionConfig`
-- `DeploymentOption`
-- `PluginCompatibility`
-- `PluginItem`
-- `PluginListResponse`
-- `PluginManifest`
-- `DiscoveryDocument`
-- `MarketSDKOptions`
+The SDK throws standard errors with detailed information:
 
-## 兼容性
+```typescript
+try {
+  await market.plugins.getPluginList();
+} catch (error) {
+  console.error('Error code:', error.code);
+  console.error('Error message:', error.message);
+  console.error('Error details:', error.details);
+}
+```
 
-此SDK使用了原生fetch API，适用于:
+## Contributing
 
-- 现代浏览器
-- Node.js 18+
-- Deno
-- Bun
-- 其他支持fetch API的运行时
+We welcome contributions! Please see our [contributing guidelines](https://github.com/lobehub/lobehub-market/blob/main/CONTRIBUTING.md) for details.
 
-## 许可证
+## License
 
 MIT