一个用于 Firefox 接码平台的 TypeScript/JavaScript SDK,提供完整的 API 接口封装。
- 🚀 完整的 TypeScript 类型支持
- 📝 详细的 JSDoc 文档
- 🔄 自动重试机制
- 🛡️ 错误处理和验证
- 📱 支持多次收码
- 🎯 智能验证码提取
- 🌐 URL 编码处理
使用 bun 安装:
bun add @pddo/firefox-api
使用 npm 安装:
npm install @pddo/firefox-api
import FirefoxApi from '@pddo/firefox-api';
const client = new FirefoxApi({
timeout: 30000, // 请求超时时间
retries: 3 // 重试次数
});
// 登录获取 Token
const loginResult = await client.login({
ApiName: 'your_api_name', // 您的 API 用户名
PassWord: 'your_password' // 您的登录密码
});
if (loginResult.success) {
console.log('登录成功,Token:', loginResult.token);
}
// 获取手机号
const phoneResult = await client.getPhone({
token: loginResult.token!,
iid: '1001', // 项目ID
country: 'CN' // 可选:指定国家代码
});
if (phoneResult.success) {
console.log('手机号:', phoneResult.mobile);
console.log('Pkey:', phoneResult.pkey);
// 等待并获取验证码
const messageResult = await client.getMessage({
token: loginResult.token!,
pkey: phoneResult.pkey!
});
if (messageResult.success) {
console.log('短信内容:', messageResult.sms);
console.log('验证码:', messageResult.code);
}
}
async function waitForCode(client: FirefoxApi, token: string, pkey: string) {
const maxRetries = 10;
let retryCount = 0;
while (retryCount < maxRetries) {
const messageResult = await client.getMessage({ token, pkey });
if (messageResult.success && messageResult.sms) {
console.log('收到验证码:', messageResult.code);
return messageResult;
}
console.log(`第${retryCount + 1}次尝试,暂未收到验证码...`);
await new Promise(resolve => setTimeout(resolve, 5000));
retryCount++;
}
console.log('等待验证码超时');
return null;
}
// 如果没有收到验证码,应该释放手机号
const releaseResult = await client.releasePhone({
token: loginResult.token!,
pkey: phoneResult.pkey!
});
if (releaseResult.success) {
console.log('手机号释放成功');
}
new FirefoxApi(config?: FirefoxApiConfig)
配置选项:
-
baseUrl?: string
- API 基础 URL(默认:'http://www.firefox.fun') -
timeout?: number
- 请求超时时间,单位毫秒(默认:30000) -
retries?: number
- 重试次数(默认:0)
login(params: LoginParams): Promise<LoginResponse>
参数:
-
ApiName: string
- API 用户名 -
PassWord: string
- 登录密码
getAccountInfo(): Promise<AccountInfoResponse>
返回用户余额、等级和积分信息。
getPhone(params: GetPhoneParams): Promise<GetPhoneResponse>
参数:
-
token: string
- 登录 Token -
iid: string
- 项目 ID -
country?: string
- 国家代码(可选) -
did?: string
- 开发者 ID(可选) -
dock?: '0' | '1'
- 是否返回对接码(可选) -
maxPrice?: number
- 最大单价(可选) -
mobile?: string
- 指定号段或手机号(可选) -
pushUrl?: string
- 推送链接(可选)
getMessage(params: GetMessageParams): Promise<GetMessageResponse>
参数:
-
token: string
- 登录 Token -
pkey: string
- 手机号唯一标识
releasePhone(params: ReleasePhoneParams): Promise<BaseResponse>
参数:
-
token: string
- 登录 Token -
pkey: string
- 手机号唯一标识
blacklistPhone(params: BlacklistPhoneParams): Promise<BaseResponse>
参数:
-
token: string
- 登录 Token -
pkey: string
- 手机号唯一标识 -
reason: string
- 加黑原因
sendSms(params: SendSmsParams): Promise<SendSmsResponse>
参数:
-
token: string
- 登录 Token -
pkey: string
- 手机号唯一标识 -
msg: string
- 短信内容 -
voice?: '0' | '1'
- 是否语音(可选)
getItemList(params?: GetItemParams): Promise<GetItemResponse>
参数:
-
key?: string
- 项目名称关键字(可选)
apiReturn(params: ApiReturnParams): Promise<BaseResponse>
参数:
-
token: string
- 登录 Token -
pkey: string
- 手机号唯一标识 -
remark: '0' | '-1' | '-2' | '-3' | string
- 反馈信息
setAgain(params: SetAgainParams): Promise<BaseResponse>
参数:
-
token: string
- 登录 Token -
pkey: string
- 手机号唯一标识 -
min?: number
- 多少分钟后再次使用(2-300,默认5)
setToken(token: string): void // 设置 Token
getToken(): string | undefined // 获取当前 Token
clearToken(): void // 清除 Token
对于需要多次接收验证码的场景,可以使用指定手机号再次获取:
// 第一次获取手机号
const phoneResult = await client.getPhone({
token: token,
iid: '1001'
});
// 第一次收码
const firstMessage = await client.getMessage({
token: token,
pkey: phoneResult.pkey!
});
// 第二次收码 - 指定使用相同手机号
const secondPhoneResult = await client.getPhone({
token: token,
iid: '1001',
mobile: phoneResult.mobile // 指定手机号
});
const secondMessage = await client.getMessage({
token: token,
pkey: secondPhoneResult.pkey!
});
SDK 提供了完整的错误代码映射:
import { ERROR_CODES } from '@pddo/firefox-api';
const result = await client.login(params);
if (!result.success) {
switch (result.errorCode) {
case ERROR_CODES.LOGIN_WRONG_CREDENTIALS:
console.log('用户名或密码错误');
break;
case ERROR_CODES.LOGIN_ACCOUNT_DISABLED:
console.log('账号已被禁用');
break;
default:
console.log('未知错误:', result.error);
}
}
SDK 内置智能验证码提取功能,支持多种常见格式:
- 纯数字验证码(4-8位)
- "验证码:123456" 格式
- "code: 123456" 格式
- 其他常见中文格式
提取的验证码通过 GetMessageResponse.code
字段返回。
-
及时释放手机号:如果没有收到验证码,请务必调用
releasePhone()
方法释放手机号,避免余额扣费。 -
控制请求频率:建议在循环获取验证码时添加适当的延迟(如5秒),避免过于频繁的请求。
-
错误处理:建议对所有 API 调用进行适当的错误处理。
-
Token 管理:Token 在未修改账户密码前保持不变,建议缓存使用。
# 安装依赖
bun install
# 构建
bun run build
# 开发模式
bun run dev
# 格式化代码
bun run format
# 代码检查
bun run lint
本项目配置了自动版本管理和npm发布功能。
# 正常提交代码
git add .
git commit -m "修复了一个bug"
git push origin main
推送到main分支后,系统会自动:
- ✅ 更新版本号(patch:1.0.0 → 1.0.1)
- ✅ 创建GitHub Release
- ✅ 发布到npm
如果不想触发发布,在commit消息中添加 [skip release]
:
git commit -m "更新文档 [skip release]"
GitHub设置(必需):
- 获取npm token:登录npmjs.com → Account Settings → Access Tokens → Generate New Token (Automation)
- 在GitHub仓库设置中添加Secret:
NPM_TOKEN
= 您的npm token
详细配置说明请参考:scripts/setup-release.md
欢迎提交Issue和Pull Request!
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature
) - 提交更改 (
git commit -m 'feat: add amazing feature'
) - 推送到分支 (
git push origin feature/amazing-feature
) - 创建Pull Request
- 使用TypeScript
- 遵循ESLint配置
- 添加适当的注释和文档
- 确保构建通过
MIT
如有问题请提交 Issue 或联系技术支持。
注意:使用本 SDK 前请确保您已注册 Firefox 接码平台账户并获得相应的 API 权限。