npm package: 115pan-node
Description: [![npm version](https://img.shields.io/npm/v/115pan-node.svg)](https://www.npmjs.com/package/115pan-node) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Bun](https://img.shields.io/badge/runt
Latest version: 0.0.2

# 115pan-node

[![npm version](https://img.shields.io/npm/v/115pan-node.svg)](https://www.npmjs.com/package/115pan-node)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Bun](https://img.shields.io/badge/runtime-bun-black)](https://bun.sh)

一个用于 115 网盘的 Node.js/Bun SDK，支持二维码登录、文件管理、下载链接获取等功能。

A Node.js/Bun SDK for 115 Cloud Drive (115网盘), featuring QR code login, file management, download URL retrieval, and more.

## 特性

- 🔐 **二维码登录** - 支持扫码登录，自动保存 cookies
- 📁 **文件系统操作** - 列目录、搜索、创建文件夹、移动/复制/删除文件
- ⬇️ **下载链接获取** - 获取文件的下载直链
- 📤 **上传支持** - 支持文件上传
- 🔗 **离线下载/分享** - 离线任务与分享链接管理
- 🍪 **Cookie 管理** - 自动持久化 cookies，支持自动重登录

## 安装

```bash
# Using bun (recommended)
bun add 115pan-node

# Using npm
npm install 115pan-node

# Using yarn
yarn add 115pan-node

# Using pnpm
pnpm add 115pan-node
```

## 快速开始

### 创建客户端

```typescript
import { P115Client } from "115pan-node";

// 方式 1: 从 cookies 字符串创建
const client = new P115Client("UID=xxx; CID=xxx; SEID=xxx");

// 方式 2: 从 cookies 文件创建（推荐）
const client = await P115Client.fromPath("./115-cookies.txt");

// 方式 3: 空客户端，稍后登录
const client = new P115Client();
```

### 二维码登录

```typescript
import { P115Client } from "115pan-node";
import qrcodeTerminal from "qrcode-terminal";

const client = new P115Client(undefined, {
  cookiesPath: "./115-cookies.txt", // 自动保存 cookies
});

await client.loginWithQrcode(
  "web",
  (qrcodeUrl, uid) => {
    // 在终端打印 ASCII 二维码
    qrcodeTerminal.generate(qrcodeUrl, { small: true }, console.log);
    console.log(`请用 115 App 扫码登录 (UID: ${uid})`);
  },
  (status) => {
    // status: 0=等待扫码, 1=已扫描待确认, 2=登录成功
    console.log("状态:", status);
  }
);

console.log("登录成功！用户 ID:", client.userId);
```

### 文件操作

```typescript
// 列出目录
const result = await client.fsFiles({ cid: 0, limit: 50 });
console.log("文件列表:", result.data);

// 搜索文件
const search = await client.fsSearch({ search_value: "关键词", cid: 0 });

// 创建文件夹
await client.fsMkdir({ cid: 0, file_name: "新建文件夹" });

// 移动文件
await client.fsMove({ fid: "文件ID", pid: "目标目录ID" });

// 复制文件
await client.fsCopy({ fid: "文件ID", pid: "目标目录ID" });

// 删除文件/文件夹
await client.fsDelete({ fid: "文件ID" });
```

### 获取下载链接

```typescript
// 获取文件下载链接
const download = await client.downloadUrlWeb({ pickcode: "文件提取码" });
console.log("下载地址:", download.file_url);

// 批量获取
const batch = await client.downloadUrlApp({ pickcode: "code1,code2,code3" });
```

### 分享链接

```typescript
// 获取分享链接信息
const info = await client.shareInfo({ share_code: "分享码" });

// 保存分享文件到网盘
await client.shareReceive({
  share_code: "分享码",
  receive_code: "提取码",
  fid: "文件ID",
  cid: "目标目录ID"
});
```

## API 参考

### P115Client

主客户端类，提供所有 API 方法。

#### 构造函数

```typescript
new P115Client(cookies?, options?)
```

- `cookies`: 可选，cookies 字符串或对象
- `options`:
  - `cookiesPath`: cookies 文件路径，自动读写
  - `checkForRelogin`: 是否在收到 405 响应时自动重新登录

#### 静态方法

```typescript
P115Client.fromPath(path, options?): Promise<P115Client>
```

从文件读取 cookies 并创建客户端实例。

#### 文件系统方法

| 方法 | 说明 |
|------|------|
| `fsFiles({ cid, limit, offset, ... })` | 列出目录内容 |
| `fsSearch({ search_value, cid, ... })` | 搜索文件 |
| `fsMkdir({ cid, file_name })` | 创建文件夹 |
| `fsMove({ fid, pid })` | 移动文件 |
| `fsCopy({ fid, pid })` | 复制文件 |
| `fsDelete({ fid })` | 删除文件 |
| `fsRename({ fid, file_name })` | 重命名 |
| `fsInfo({ fid })` | 获取文件信息 |
| `fsGetPath({ fid })` | 获取文件路径 |

#### 下载方法

| 方法 | 说明 |
|------|------|
| `downloadUrlWeb({ pickcode })` | 获取下载链接（Web 接口） |
| `downloadUrlApp({ pickcode })` | 获取下载链接（App 接口） |
| `downloadFolders({ pickcode })` | 获取下载文件夹列表 |
| `downloadFiles({ pickcode })` | 获取下载文件列表 |

#### 登录方法

| 方法 | 说明 |
|------|------|
| `loginQrcodeToken(app)` | 获取二维码 token |
| `loginQrcodeScanStatus({ uid, time, sign })` | 查询扫码状态 |
| `loginQrcodeScanResult(uid, app)` | 获取登录结果 |
| `loginWithQrcode(app, onQrcode, onStatus)` | 完整扫码登录流程 |

#### 分享方法

| 方法 | 说明 |
|------|------|
| `shareInfo({ share_code })` | 获取分享信息 |
| `shareReceive({ share_code, receive_code, ... })` | 保存分享文件 |
| `offlineTaskAdd({ url })` | 添加离线任务 |

## 运行演示

```bash
# 克隆项目
git clone https://github.com/yourusername/115pan-node.git
cd 115pan-node

# 安装依赖
bun install

# 运行演示（扫码登录）
bun run demo

# 使用保存的 cookies
bun run demo:save
```

## 开发

```bash
# 运行测试
bun test

# 构建产物
bun build ./index.ts --outdir ./dist
```

## 类型导出

```typescript
// 主要类型
export type { P115ClientOptions, RequestOptions };
export type { P115CookiesData, DirNode, P115URL };

// 错误类
export {
  P115OSError,
  P115AuthenticationError,
  P115BusyOSError,
  P115DataError,
  P115OperationalError,
  P115AccessError,
  P115FileTooBig,
  P115ExceededError,
  P115InvalidArgumentError,
  P115NoSpaceError,
  P115NotSupportedError,
  P115LoginError,
};
```

## 注意事项

- 本项目为非官方 SDK，仅供学习研究使用
- 请合理使用 API，避免频繁请求
- Cookies 包含敏感信息，请妥善保管

## License

[MIT](LICENSE)

## 贡献

欢迎提交 Issue 和 Pull Request！