模拟搜索 API 客户端

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

特征

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

为什么要抓?

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

安装

npm install @cimulate/search-sdk

快速启动

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(): 获得可用建议组

搜索示例

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, 建议和重新排序示例

// 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']
};

会议和活动管理

// 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);

处理错误

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
  }
}