# @cimulate/search-sdk 中文文档

规范地址：https://npmcn.com/package/%40cimulate/search-sdk/

版本：2\.0\.0
npm 元数据更新时间：2026-06-04T14:59:07.450Z
中文译文更新时间：2026-11-09T16:13:12.884Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cimulate/search-sdk
原文对照：https://npmcn.com/package/%40cimulate/search-sdk/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：269 kB，57 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-04-15T23:11:38.609Z
- 最新版本发布：2026-06-04T14:59:07.235Z
- 近 30 天下载量：2845（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 2 个）

## 中文简介

模拟搜索功能的轻量级 API 客户端 SDK

## 安装

```sh
npm install @cimulate/search-sdk
```

也可以使用：`pnpm add @cimulate/search-sdk`、`yarn add @cimulate/search-sdk`、`bun add @cimulate/search-sdk`

## README

# 模拟搜索 API 客户端

用于与 Cimulate 搜索 API (v1.4. 0) 交互的 Script 客户端.

## 特征

-   强烈输入的请求和响应对象
-   以指数回转自动重试
-   全面处理错误
-   处理网络问题的再连接逻辑
-   零依赖( 使用本地获取 API)
-   伐木能力

## 为什么要抓?

这个客户端使用"本地获取API",因为它提供零依赖,使用现代标准,提供基于承诺的界面,并且在所有现代浏览器和Node.js(v18+)环境中都可以使用.

## 安装

```bash
npm install @cimulate/search-sdk
```

## 快速启动

```typescript
import { CimulateSearchClient } from '@cimulate/search-sdk';
import { SearchRequest } from '@cimulate/search-sdk';

// Initialize with API key or token
const client = new CimulateSearchClient({
  apiKey: 'your-api-key-here',
  // OR token: 'your-bearer-token',
  baseURL: 'https://prod.search.cimulate.ai/api/v1',
  options: {
    maxRetries: 5,        // Default: 3
    baseDelay: 500,       // Default: 300ms
    timeout: 30000,       // Default: 10000ms
    enableLogging: true   // Default: false
  }
});

// Connect and verify API credentials
await client.connect();
const version = await client.getVersion();
console.log(`API Version: ${version.version}`);

// Perform a search
const results = await client.search({ query: 'running shoes' });
console.log(`Found ${results.total_hits} products`);
```

## API 方法

客户端为所有 Cimulate API 终端提供方法 :

-   `getVersion()`: 获取 API 版本
-   `search(request)`: 进行搜索
-   `getFacets(request)`: 获取表面数据
-   `getSuggestions(request)`: 获取搜索建议
-   `rerankProducts(request)`: 调整搜索结果
-   `getProductsByIds(request)`:通过身份证获取产品
-   `createSession(request)`: 创建用户会话
-   `getSessionById(id)`: 获取会话细节
-   `updateSessionById(id, request)`: 更新会话
-   `deleteSessionById(id)`: 删除会话
-   `createEvent(sessionId, request)`: 创建会话事件
-   `getAllEventsBySessionId(sessionId)`: 获取全部会话活动
-   `getEventById(sessionId, eventId)`: 获取特定事件
-   `deleteEventById(sessionId, eventId)`: 删除事件
-   `getRecommendations(request)`: 获取建议
-   `getRecommendationsGroups()`: 获得可用建议组

## 搜索示例

```typescript
import { SearchRequest } from '@cimulate/search-sdk';

// Simple search
const basicSearch: SearchRequest = {
  query: 'running shoes'
};

// Advanced search with filters and facets
const advancedSearch: SearchRequest = {
  query: 'running shoes',
  page: 1,
  page_size: 20,
  include_facets: true,
  range_filters: [
    {
      field: 'price',
      max: 200,
      min: 50
    }
  ],
  facet_filters: {
    category: ["shoes", "clothing"],
    brand: ["Nike", "Adidas", "Puma"],
    color: ["red", "black", "white"]
  },
  sorting_options: ["newest"],
  session_data: {
    ga_session_id: "ga-session-123",
    session_id: "user-session-123",
    sfcc_sid: "sfcc-sid-456"
  }
};
```

## Facet, 建议和重新排序示例

```typescript
// Facets request
const facetRequest = {
  query: 'running shoes',
  max_size: 10,
  range_filters: [{ field: 'price', max: 200, min: 50 }],
  facet_filters: { category: ["shoes", "clothing"] }
};

// Suggestions request
const suggestRequest = {
  query: 'run',
  size: 5
};

// Rerank request
const rerankRequest = {
  query: 'Lil Wayne',
  results: [{ productId: '448479100' }],
  referrer: 'search_page',
  pinned_ranks: { "246675600": 1 }
};

// Get products by ID
const idRequest = {
  ids: ['478942125']
};
```

## 会议和活动管理

```typescript
// Create a session
const session = await client.createSession({
  data: { 
    products_in_cart: 3,
    ga_session_id: "ga-session-123",
    ga_pseudo_user_id: "ga-user-123"
  },
  metadata: { source: 'web', device: 'mobile' }
});

// Session operations
const sessionDetails = await client.getSessionById(session.id);
await client.updateSessionById(session.id, {
  data: { products_in_cart: 5 },
  metadata: { last_page: 'checkout' }
});

// Event operations
const event = await client.createEvent(session.id, {
  name: 'product_view',
  data: { product_id: '473174149', time_spent: 45 },
  metadata: { referrer: 'search' }
});
const events = await client.getAllEventsBySessionId(session.id);
await client.deleteEventById(session.id, event.id);
```

## 处理错误

```typescript
import { CimulateSearchClient } from '@cimulate/search-sdk';
import { CimulateSearchClientError, CimulateError } from '@cimulate/search-sdk';

try {
  const results = await client.search({ query: 'running shoes' });
} catch (error) {
  // If it's already one of our error types, use it directly
  if (CimulateSearchClientError.isCimulateError(error)) {
    console.error("Search client error", error.getDetailMessage());
    throw error; // Re-throw if needed
  }
}
```

## 常见问题

### @cimulate/search-sdk 是什么？

模拟搜索功能的轻量级 API 客户端 SDK

### 如何安装 @cimulate/search-sdk？

在项目目录运行 npm install @cimulate/search-sdk，或使用 pnpm add / yarn add / bun add。

### @cimulate/search-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cimulate/search-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cimulate/search-sdk 可以商用吗？

@cimulate/search-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cimulate/search-sdk 的下载量有多少？

根据 npm 官方下载统计，@cimulate/search-sdk 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,845 次，日均约 95 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cimulate/search-sdk 还在维护吗？

最新版本 2\.0\.0 发布于 2026/06/04（5 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 2 个；首次发布于 2025/04/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。