@quantabit/recommend-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantaBit Team
+
+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/README.md

@@ -0,0 +1,85 @@
+# @quantabit/recommend-sdk
+
+> QuantaBit Recommendation SDK - Personalized content/product recommendations and cold-start strategies
+
+## 📦 Installation
+
+```bash
+npm install @quantabit/recommend-sdk
+# or
+yarn add @quantabit/recommend-sdk
+```
+
+## 🚀 Quick Start
+
+### Using Components
+
+```jsx
+import { RecommendCard, RecommendSection, GuessYouLike, SimilarItems } from '@quantabit/recommend-sdk';
+
+<RecommendCard />
+<RecommendSection />
+<GuessYouLike />
+```
+
+### Using Hooks
+
+```jsx
+import { useRecommendations, useSimilar, useHomeFeed, useColdStart, useRecommend } from '@quantabit/recommend-sdk';
+
+function MyComponent() {
+  const result = useRecommendations();
+  const result = useSimilar();
+  const result = useHomeFeed();
+  return <div>...</div>;
+}
+```
+
+### API Client
+
+```javascript
+import { recommendApi } from '@quantabit/recommend-sdk';
+
+// Use recommendApi for direct API calls
+const data = await recommendApi.list();
+```
+
+## 📚 Components
+
+| Component | Description |
+| --------- | ----------- |
+| `RecommendCard` | Recommend Card component |
+| `RecommendSection` | Recommend Section component |
+| `GuessYouLike` | Guess You Like component |
+| `SimilarItems` | Similar Items component |
+
+## 🪝 Hooks
+
+| Hook | Description |
+| ---- | ----------- |
+| `useRecommendations` | Recommendations management |
+| `useSimilar` | Similar management |
+| `useHomeFeed` | Home Feed management |
+| `useColdStart` | Cold Start management |
+| `useRecommend` | Recommend management |
+
+## 📖 Type Definitions
+
+```javascript
+import { RecommendType, RecommendAlgorithm, RecommendScene, FeedbackType } from '@quantabit/recommend-sdk';
+```
+
+## 📄 License
+
+MIT License
+
+
+
+---
+
+## 🌐 Brand & Links
+- Official Mainnet: [QuantaBit Chain](https://qbitchain.io/)
+- Developer Platform: [Developer Platform](https://developer.quantabit.io/)
+- Open Platform: [Open Platform](https://open.quantabit.io/)
+- Payment Platform: [Pay Platform](https://pay.qbitwallet.io/)
+- Feedback: [Feedback](https://xwin.live/qbit)

package/dist/index.cjs

@@ -0,0 +1,616 @@
+'use strict';
+
+var sdkConfig = require('@quantabit/sdk-config');
+var react = require('react');
+
+/**
+ * Recommend SDK - API 客户端
+ * 推荐系统后端接口封装
+ * 
+ * 使用 BaseApiClient 基类简化代码
+ */
+
+
+/**
+ * 推荐 API 客户端
+ */
+class RecommendApiClient extends sdkConfig.BaseApiClient {
+  constructor(config = {}) {
+    super('/recommend', config);
+  }
+
+  // ============ 个性化推荐 ============
+
+  /**
+   * 获取首页推荐
+   * @param {Object} params - 推荐参数
+   */
+  async getHomeRecommendations(params = {}) {
+    return this.get('/home', params);
+  }
+  async getHomeFeed(params = {}) {
+    return this.getHomeRecommendations(params);
+  }
+  async getRecommendations(type = 'home', params = {}) {
+    return this.get(`/${type}`, params);
+  }
+
+  /**
+   * 获取内容推荐
+   * @param {Object} params - 推荐参数
+   */
+  async getContentRecommendations(params = {}) {
+    return this.get('/content', params);
+  }
+
+  /**
+   * 获取商品推荐
+   * @param {Object} params - 推荐参数
+   */
+  async getProductRecommendations(params = {}) {
+    return this.get('/products', params);
+  }
+
+  /**
+   * 获取用户推荐（可能认识的人）
+   * @param {Object} params - 推荐参数
+   */
+  async getUserRecommendations(params = {}) {
+    return this.get('/users', params);
+  }
+
+  // ============ 相关推荐 ============
+
+  /**
+   * 获取相关内容
+   * @param {string} contentId - 内容 ID
+   * @param {Object} params - 推荐参数
+   */
+  async getRelatedContent(contentId, params = {}) {
+    return this.get(`/related/content/${contentId}`, params);
+  }
+  async getSimilar(itemType, itemId, limit = 10) {
+    return this.get(`/related/${itemType}/${itemId}`, {
+      limit
+    });
+  }
+
+  /**
+   * 获取相关商品
+   * @param {string} productId - 商品 ID
+   * @param {Object} params - 推荐参数
+   */
+  async getRelatedProducts(productId, params = {}) {
+    return this.get(`/related/product/${productId}`, params);
+  }
+
+  /**
+   * 获取相似用户
+   * @param {string} userId - 用户 ID
+   * @param {Object} params - 推荐参数
+   */
+  async getSimilarUsers(userId, params = {}) {
+    return this.get(`/related/user/${userId}`, params);
+  }
+
+  // ============ 场景推荐 ============
+
+  /**
+   * 获取猜你喜欢
+   * @param {Object} params - 推荐参数
+   */
+  async getGuessYouLike(params = {}) {
+    return this.get('/guess-you-like', params);
+  }
+  async getAlsoViewed(itemId, itemType = 'content', params = {}) {
+    return this.get('/also-viewed', {
+      item_id: itemId,
+      item_type: itemType,
+      ...params
+    });
+  }
+  async getAlsoBought(itemId, itemType = 'product', params = {}) {
+    return this.get('/also-bought', {
+      item_id: itemId,
+      item_type: itemType,
+      ...params
+    });
+  }
+
+  /**
+   * 获取热门推荐
+   * @param {Object} params - 推荐参数
+   */
+  async getHotRecommendations(params = {}) {
+    return this.get('/hot', params);
+  }
+
+  /**
+   * 获取新品推荐
+   * @param {Object} params - 推荐参数
+   */
+  async getNewRecommendations(params = {}) {
+    return this.get('/new', params);
+  }
+
+  /**
+   * 获取专题推荐
+   * @param {string} topicId - 专题 ID
+   * @param {Object} params - 推荐参数
+   */
+  async getTopicRecommendations(topicId, params = {}) {
+    return this.get(`/topic/${topicId}`, params);
+  }
+
+  // ============ 反馈 ============
+
+  /**
+   * 不感兴趣
+   * @param {string} itemId - 项目 ID
+   * @param {string} itemType - 项目类型
+   * @param {string} reason - 原因
+   */
+  async notInterested(itemId, itemType, reason = '') {
+    return this.post('/feedback/not-interested', {
+      item_id: itemId,
+      item_type: itemType,
+      reason
+    });
+  }
+  async markNotInterested(itemType, itemId, reason = '') {
+    return this.notInterested(itemId, itemType, reason);
+  }
+  async feedback(itemType, itemId, feedbackType, context = {}) {
+    return this.post('/feedback', {
+      item_type: itemType,
+      item_id: itemId,
+      feedback_type: feedbackType,
+      ...context
+    });
+  }
+
+  /**
+   * 记录点击
+   * @param {string} itemId - 项目 ID
+   * @param {string} itemType - 项目类型
+   * @param {Object} context - 上下文
+   */
+  async trackClick(itemId, itemType, context = {}) {
+    return this.post('/feedback/click', {
+      item_id: itemId,
+      item_type: itemType,
+      ...context
+    });
+  }
+
+  /**
+   * 记录曝光
+   * @param {Object[]} items - 曝光项目列表
+   */
+  async trackExposure(items) {
+    return this.post('/feedback/exposure', {
+      items
+    });
+  }
+
+  // ============ 偏好设置 ============
+
+  /**
+   * 获取推荐偏好
+   */
+  async getPreferences() {
+    return this.get('/preferences');
+  }
+  async getUserPreferences() {
+    return this.getPreferences();
+  }
+
+  /**
+   * 更新推荐偏好
+   * @param {Object} preferences - 偏好设置
+   */
+  async updatePreferences(preferences) {
+    return this.put('/preferences', preferences);
+  }
+
+  /**
+   * 获取兴趣标签
+   */
+  async getInterestTags() {
+    return this.get('/interests');
+  }
+
+  /**
+   * 更新兴趣标签
+   * @param {string[]} tagIds - 标签 ID 列表
+   */
+  async updateInterestTags(tagIds) {
+    return this.put('/interests', {
+      tag_ids: tagIds
+    });
+  }
+  async getColdStartQuestions(params = {}) {
+    return this.get('/cold-start/questions', params);
+  }
+  async submitColdStartAnswers(answers) {
+    return this.post('/cold-start/answers', {
+      answers
+    });
+  }
+}
+
+// 创建默认实例
+const recommendApi = new RecommendApiClient();
+
+/**
+ * Recommend SDK - 类型定义
+ */
+
+// 推荐类型
+const RecommendType = {
+  CONTENT: 'content',
+  PRODUCT: 'product',
+  USER: 'user',
+  COURSE: 'course',
+  GROUP: 'group',
+  ACTIVITY: 'activity'
+};
+
+// 推荐算法
+const RecommendAlgorithm = {
+  COLLABORATIVE: 'collaborative',
+  // 协同过滤
+  CONTENT_BASED: 'content_based',
+  // 基于内容
+  HYBRID: 'hybrid',
+  // 混合推荐
+  POPULARITY: 'popularity',
+  // 热门推荐
+  TRENDING: 'trending',
+  // 趋势推荐
+  SIMILAR: 'similar' // 相似推荐
+};
+
+// 场景
+const RecommendScene = {
+  HOME_FEED: 'home_feed',
+  DETAIL_PAGE: 'detail_page',
+  SEARCH_RESULT: 'search_result',
+  CART: 'cart',
+  CHECKOUT: 'checkout',
+  PROFILE: 'profile'
+};
+
+// 反馈类型
+const FeedbackType = {
+  CLICK: 'click',
+  VIEW: 'view',
+  LIKE: 'like',
+  DISLIKE: 'dislike',
+  SHARE: 'share',
+  PURCHASE: 'purchase',
+  NOT_INTERESTED: 'not_interested'
+};
+
+/**
+ * Recommend SDK - React Hooks
+ */
+
+
+/**
+ * useRecommendations - 推荐列表Hook
+ */
+function useRecommendations(type, options = {}) {
+  const [items, setItems] = react.useState([]);
+  const [loading, setLoading] = react.useState(false);
+  const [refreshing, setRefreshing] = react.useState(false);
+  const loadRecommendations = react.useCallback(async (isRefresh = false) => {
+    if (isRefresh) {
+      setRefreshing(true);
+    } else {
+      setLoading(true);
+    }
+    try {
+      const result = await recommendApi.getRecommendations(type, options);
+      setItems(result.items || []);
+    } finally {
+      setLoading(false);
+      setRefreshing(false);
+    }
+  }, [type, options.scene, options.limit, options.algorithm]);
+
+  // 提交反馈
+  const feedback = react.useCallback(async (itemId, feedbackType) => {
+    try {
+      await recommendApi.feedback(type, itemId, feedbackType);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }, [type]);
+
+  // 标记不感兴趣
+  const markNotInterested = react.useCallback(async (itemId, reason) => {
+    try {
+      await recommendApi.markNotInterested(type, itemId, reason);
+      // 从列表中移除
+      setItems(prev => prev.filter(item => item.id !== itemId));
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }, [type]);
+
+  // 刷新
+  const refresh = react.useCallback(() => {
+    return loadRecommendations(true);
+  }, [loadRecommendations]);
+  react.useEffect(() => {
+    loadRecommendations();
+  }, [type, options.scene]);
+  return {
+    items,
+    loading,
+    refreshing,
+    refresh,
+    feedback,
+    markNotInterested
+  };
+}
+
+/**
+ * useSimilar - 相似推荐Hook
+ */
+function useSimilar(itemType, itemId, limit = 10) {
+  const [items, setItems] = react.useState([]);
+  const [loading, setLoading] = react.useState(false);
+  const loadSimilar = react.useCallback(async () => {
+    if (!itemType || !itemId) return;
+    setLoading(true);
+    try {
+      const result = await recommendApi.getSimilar(itemType, itemId, limit);
+      setItems(result.items || []);
+    } finally {
+      setLoading(false);
+    }
+  }, [itemType, itemId, limit]);
+  react.useEffect(() => {
+    loadSimilar();
+  }, [itemType, itemId]);
+  return {
+    items,
+    loading,
+    refresh: loadSimilar
+  };
+}
+
+/**
+ * useHomeFeed - 首页Feed Hook
+ */
+function useHomeFeed() {
+  const [items, setItems] = react.useState([]);
+  const [loading, setLoading] = react.useState(false);
+  const [refreshing, setRefreshing] = react.useState(false);
+  const [page, setPage] = react.useState(1);
+  const [hasMore, setHasMore] = react.useState(true);
+  const loadFeed = react.useCallback(async (reset = false) => {
+    const currentPage = reset ? 1 : page;
+    if (reset) {
+      setRefreshing(true);
+    } else {
+      setLoading(true);
+    }
+    try {
+      const result = await recommendApi.getHomeFeed({
+        page: currentPage,
+        pageSize: 20
+      });
+      const newItems = result.items || [];
+      setItems(prev => reset ? newItems : [...prev, ...newItems]);
+      setHasMore(newItems.length >= 20);
+      if (reset) setPage(1);
+    } finally {
+      setLoading(false);
+      setRefreshing(false);
+    }
+  }, [page]);
+  const loadMore = react.useCallback(() => {
+    if (hasMore && !loading) {
+      setPage(p => p + 1);
+    }
+  }, [hasMore, loading]);
+  const refresh = react.useCallback(() => {
+    return loadFeed(true);
+  }, [loadFeed]);
+  react.useEffect(() => {
+    loadFeed(true);
+  }, []);
+  react.useEffect(() => {
+    if (page > 1) loadFeed();
+  }, [page]);
+  return {
+    items,
+    loading,
+    refreshing,
+    hasMore,
+    loadMore,
+    refresh
+  };
+}
+
+/**
+ * useColdStart - 冷启动引导Hook
+ */
+function useColdStart() {
+  const [questions, setQuestions] = react.useState([]);
+  const [answers, setAnswers] = react.useState({});
+  const [loading, setLoading] = react.useState(false);
+  const [submitting, setSubmitting] = react.useState(false);
+  const [completed, setCompleted] = react.useState(false);
+  const loadQuestions = react.useCallback(async () => {
+    setLoading(true);
+    try {
+      const result = await recommendApi.getColdStartQuestions();
+      setQuestions(result.questions || []);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+  const setAnswer = react.useCallback((questionId, answer) => {
+    setAnswers(prev => ({
+      ...prev,
+      [questionId]: answer
+    }));
+  }, []);
+  const submit = react.useCallback(async () => {
+    setSubmitting(true);
+    try {
+      await recommendApi.submitColdStartAnswers(answers);
+      setCompleted(true);
+      return true;
+    } catch (e) {
+      return false;
+    } finally {
+      setSubmitting(false);
+    }
+  }, [answers]);
+  react.useEffect(() => {
+    loadQuestions();
+  }, []);
+  return {
+    questions,
+    answers,
+    loading,
+    submitting,
+    completed,
+    setAnswer,
+    submit,
+    isComplete: Object.keys(answers).length >= questions.length
+  };
+}
+
+function RecommendCard() {
+  return null;
+}
+function RecommendSection() {
+  return null;
+}
+function GuessYouLike() {
+  return null;
+}
+function SimilarItems() {
+  return null;
+}
+
+/**
+ * QuantaBit Recommend SDK - i18n support
+ */
+
+const messages = {
+  en: {
+    recommendation: 'Recommendations',
+    guessYouLike: 'Guess You Like',
+    similarItems: 'Similar Items',
+    alsoViewed: 'People also viewed',
+    alsoBought: 'People also bought',
+    notInterested: 'Not Interested',
+    notInterestedFeedback: 'We will show you fewer items like this',
+    loading: 'Loading recommendations...',
+    noData: 'No recommendations available'
+  },
+  zh: {
+    recommendation: '个性化推荐',
+    guessYouLike: '猜你喜欢',
+    similarItems: '相似推荐',
+    alsoViewed: '看了还看',
+    alsoBought: '买了还买',
+    notInterested: '不感兴趣',
+    notInterestedFeedback: '将减少此类内容的推荐',
+    loading: '正在加载推荐内容...',
+    noData: '暂无推荐内容'
+  },
+  ja: {
+    recommendation: 'おすすめ',
+    guessYouLike: 'あなたへのおすすめ',
+    similarItems: '似たような商品',
+    alsoViewed: 'この商品を見た人はこんな商品も見ています',
+    alsoBought: 'この商品を買った人はこんな商品も買っています',
+    notInterested: '興味がない',
+    notInterestedFeedback: 'このようなアイテムの表示を減らします',
+    loading: '読み込み中...',
+    noData: 'おすすめはありません'
+  },
+  ko: {
+    recommendation: '추천 콘텐츠',
+    guessYouLike: '이런 콘텐츠는 어떠세요?',
+    similarItems: '비슷한 콘텐츠',
+    alsoViewed: '함께 본 콘텐츠',
+    alsoBought: '함께 구매한 상품',
+    notInterested: '관심 없음',
+    notInterestedFeedback: '이와 같은 콘텐츠 추천을 줄입니다',
+    loading: '추천 콘텐츠를 불러오는 중...',
+    noData: '추천할 콘텐츠가 없습니다'
+  }
+};
+const SUPPORTED_LANGUAGES = ['en', 'zh', 'ja', 'ko'];
+let currentLanguage = 'en';
+function setLanguage(lang) {
+  if (SUPPORTED_LANGUAGES.includes(lang)) currentLanguage = lang;
+}
+function getLanguage() {
+  return currentLanguage;
+}
+function t(key) {
+  return (messages[currentLanguage] || messages.en)[key] || key;
+}
+
+/**
+ * @quantabit/recommend-sdk
+ * Recommendation SDK - Full Version
+ */
+
+const getRecommendations = (...args) => recommendApi.getRecommendations(...args);
+const getHomeFeed = (...args) => recommendApi.getHomeFeed(...args);
+const getSimilar = (...args) => recommendApi.getSimilar(...args);
+const getGuessYouLike = (...args) => recommendApi.getGuessYouLike(...args);
+const getAlsoViewed = (...args) => recommendApi.getAlsoViewed(...args);
+const getAlsoBought = (...args) => recommendApi.getAlsoBought(...args);
+const feedback = (...args) => recommendApi.feedback(...args);
+const markNotInterested = (...args) => recommendApi.markNotInterested(...args);
+const getUserPreferences = (...args) => recommendApi.getUserPreferences(...args);
+const updatePreferences = (...args) => recommendApi.updatePreferences(...args);
+const getColdStartQuestions = (...args) => recommendApi.getColdStartQuestions(...args);
+const submitColdStartAnswers = (...args) => recommendApi.submitColdStartAnswers(...args);
+
+exports.FeedbackType = FeedbackType;
+exports.GuessYouLike = GuessYouLike;
+exports.RecommendAlgorithm = RecommendAlgorithm;
+exports.RecommendApiClient = RecommendApiClient;
+exports.RecommendCard = RecommendCard;
+exports.RecommendScene = RecommendScene;
+exports.RecommendSection = RecommendSection;
+exports.RecommendType = RecommendType;
+exports.SUPPORTED_LANGUAGES = SUPPORTED_LANGUAGES;
+exports.SimilarItems = SimilarItems;
+exports.feedback = feedback;
+exports.getAlsoBought = getAlsoBought;
+exports.getAlsoViewed = getAlsoViewed;
+exports.getColdStartQuestions = getColdStartQuestions;
+exports.getGuessYouLike = getGuessYouLike;
+exports.getHomeFeed = getHomeFeed;
+exports.getLanguage = getLanguage;
+exports.getRecommendations = getRecommendations;
+exports.getSimilar = getSimilar;
+exports.getUserPreferences = getUserPreferences;
+exports.markNotInterested = markNotInterested;
+exports.messages = messages;
+exports.recommendApi = recommendApi;
+exports.setLanguage = setLanguage;
+exports.submitColdStartAnswers = submitColdStartAnswers;
+exports.t = t;
+exports.updatePreferences = updatePreferences;
+exports.useColdStart = useColdStart;
+exports.useHomeFeed = useHomeFeed;
+exports.useRecommendations = useRecommendations;
+exports.useSimilar = useSimilar;
+//# sourceMappingURL=index.cjs.map