goofish-client

Goofish Client

一个非官方的闲鱼客户端库，支持商品搜索、IM 会话与消息等功能。

⚠️ 免责声明

本项目仅供学习和研究目的使用。

本库为第三方开发的非官方客户端，与闲鱼平台无任何关联。使用本库需注意：

• 合规性风险：请确保您的使用符合相关平台的服务条款及适用法律法规
• 稳定性风险：非官方实现可能随时失效，不保证功能的持续可用性
• 使用风险：使用本库产生的任何后果由使用者自行承担 本项目开发者不对使用本库产生的任何直接或间接后果负责。请谨慎评估风险后使用。

📚 完整在线文档 | 🚀 快速开始 | 📖 API 参考

📋 Requirements

• Node.js >= 14.0.0
• TypeScript >= 4.5.0 (可选)
• 支持 ES2020+ 或 CommonJS

📦 Installation

npm install goofish-client

选择你喜欢的包管理器：

# NPM
npm install goofish-client

# Yarn
yarn add goofish-client

# PNPM
pnpm add goofish-client

✨ 核心功能

• 🔍 商品搜索 - 支持关键词搜索、价格筛选、地理位置筛选等
• 🏠 首页推荐 - 获取个性化商品推荐 Feed
• 📦 商品详情 - 获取商品完整信息、卖家信息等
• 👤 用户管理 - 获取用户信息、查询用户资料
• ❤️ 收藏管理 - 获取收藏列表、降价提醒等
• 📋 订单管理 - 获取订单列表、订单状态查询
• 🔐 身份认证 - 支持 Cookie、二维码、账号密码登录
• 💬 IM 即时通讯 - 完整的 IM 功能，支持会话管理、消息收发、实时推送

🚀 Quick Start

基本用法

import { Goofish, LogLevel } from "goofish-client";

// 1. 创建客户端实例
const client = new Goofish({
  cookie: "cookie2=xxxx", // 你的登录凭证
  level: LogLevel.INFO, // 可选：设置日志级别
});

// 2. 搜索商品
const results = await client.api.mtop.search.search({
  keyword: "iPhone", // 搜索关键词
  pageNumber: 1, // 页码
  rowsPerPage: 20, // 每页数量
});

// 3. 处理结果
if (results.ret[0] === "SUCCESS::调用成功") {
  console.log(`找到 ${results.data.resultList.length} 个商品`);
  results.data.resultList.forEach((item) => {
    const info = item.data.item.main.exContent;
    console.log(`${info.title} - ${info.price.map((p) => p.text).join("")}`);
  });
}

二维码登录示例

import { Goofish, QRCodeStatus } from "goofish-client";

const client = new Goofish();

// 生成二维码
const qrResult = await client.api.passport.qr.generate();
console.log("请扫描二维码:", qrResult.content.data.codeContent);

// 轮询等待确认
const { t, ck } = qrResult.content.data;
while (true) {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  const status = await client.api.passport.qr.query({ t, ck });

  if (status.content.data.qrCodeStatus === QRCodeStatus.CONFIRMED) {
    // 登录成功，更新cookie
    const cookie = client.getCookiePassport();
    client.updateCookieMtop(cookie);
    break;
  }
}

IM 消息示例

import { Goofish, LogLevel } from "goofish-client";
import type {
  GoofishMtopResponse,
  ImLoginTokenResponse,
} from "goofish-client";

// 1. 创建客户端实例（开启 IM 能力）
const client = new Goofish({
  cookie: "cookie2=xxxx",
  level: LogLevel.INFO,
  im: {
    // 可选：自定义 IM 配置
    autoReconnect: true,
  },
});

// 2. 获取 IM 登录 Token（Mtop 接口）
const tokenRes: GoofishMtopResponse<ImLoginTokenResponse> =
  await client.api.mtop.im.getLoginToken();

// 3. 连接 WebSocket 并注册 IM 服务
await client.wsClientIm.connect();
await client.api.im.auth.register({
  token: tokenRes.data.accessToken,
});

// 4. 监听格式化后的消息
client.api.im.message.onFormattedMessage((msg) => {
  // msg.text 为解析后的文本内容
  console.log("收到消息:", msg);
});

📝 Logging

日志配置

Client 内置了完整的日志系统，支持请求响应日志记录：

// 启用调试模式，查看详细的请求响应日志
const client = new Goofish({
  cookie: "cookie2=xxxx",
  level: LogLevel.DEBUG, // 启用后会显示详细的HTTP请求日志
});

// 普通模式，只显示基本信息
const client = new Goofish({
  cookie: "cookie2=xxxx",
  level: LogLevel.WARN, // 默认值，只显示基本日志
});

日志级别

• LogLevel.ERROR (0) - 只显示错误
• LogLevel.WARN (1) - 显示警告和错误
• LogLevel.INFO (2) - 显示信息、警告和错误
• LogLevel.DEBUG (3) - 显示所有日志

调试模式

设置日志级别为 LogLevel.DEBUG 即可启用详细的调试信息：

• 显示完整的请求 URL、方法、数据
• 显示详细的响应内容
• 显示请求耗时
• 自动过滤敏感信息（如 Cookie、Token 等）

📖 API Reference

核心方法

方法	描述	返回类型
client.api.mtop.search.search()	搜索商品	Promise<GoofishMtopResponse<SearchResponse>>
client.api.mtop.user.getUserHead()	获取用户信息	Promise<GoofishMtopResponse<UserHeadResponse>>
client.api.passport.qr.generate()	生成登录二维码	Promise<GoofishPassportResponse<QrGenerateResponse>>
client.api.passport.qr.query()	查询二维码状态	Promise<GoofishPassportResponse<QrQueryResponse>>
client.api.mtop.im.getLoginToken()	获取 IM 登录 Token	Promise<GoofishMtopResponse<ImLoginTokenResponse>>
client.api.im.conversation.listNewestPagination()	获取会话列表	Promise<WsResponse<ConversationListNewestPaginationResponse>>
client.api.im.message.sendTextMessage()	发送文本消息	Promise<WsResponse<SendMessageByReceiverScopeResponse>>

📝 注意: 更多 API 方法正在持续添加中，完整的 API 文档请参考 API 接口文档

配置选项

import type { GoofishConfig } from "goofish-client";

// 推荐：使用 Partial<GoofishConfig> 作为配置输入类型
const config: Partial<GoofishConfig> = {
  // 登录凭证
  cookie: "cookie2=xxxx",
  // 日志级别: ERROR, WARN, INFO, DEBUG
  level: LogLevel.DEBUG,
  // 可选：覆盖 Mtop 配置
  mtop: {
    timeout: 10000,
  },
  // 可选：Passport 配置
  passport: {
    baseURL: "https://passport.taobao.com/",
  },
  // 可选：IM 配置
  im: {
    autoReconnect: true,
    heartbeatInterval: 10000,
  },
  // 请求头
  headers: {
    userAgent: "Mozilla/5.0 ...",
  },
};

搜索参数

interface SearchOptions {
  keyword: string; // 搜索关键词 (必需)
  pageNumber?: number; // 页码，默认: 1
  rowsPerPage?: number; // 每页数量，默认: 30
  sortField?: SortField; // 排序字段: PRICE, CREATE, POSITION
  sortValue?: SortValue; // 排序方式: ASC, DESC
  gps?: GPSCoordinate; // GPS坐标
  filter?: {
    priceRange?: {
      // 价格筛选
      from: number;
      to?: number;
    };
    publishDays?: PublishDays; // 发布时间: "1", "3", "7", "14"
    quickFilters?: QuickFilter[]; // 快速筛选: PERSONAL, FREE_POSTAGE 等
  };
}

📚 More Resources

资源	描述	链接
📖 在线文档	完整的 API 参考和使用指南	GitHub Pages
💻 示例代码	完整的使用示例	examples/
🐛 问题反馈	Bug 报告和功能请求	GitHub Issues
💬 讨论交流	社区讨论和帮助	GitHub Discussions

🤝 Contributing

欢迎贡献代码！请查看 贡献指南 了解详情。

💡 使用技巧

🔧 TypeScript 类型

import type { SearchOptions, SearchResponse } from "goofish-client";
import { SortField, SortValue } from "goofish-client";

const searchOptions: SearchOptions = {
  keyword: "iPhone",
  sortField: SortField.PRICE,
  sortValue: SortValue.ASC,
  filter: {
    priceRange: { from: 1000, to: 5000 },
  },
};

🌐 环境支持

• ✅ Node.js - 服务端应用（Node.js >= 14.0.0）
• ✅ Electron - 桌面应用
• ✅ Next.js - 服务端渲染
• ✅ Nuxt.js - 服务端渲染

👥 Contributors

📊 GitHub Stats

⭐ Star History

📄 License

GPL-3.0 License

Copyright © 2025 11273