@ccw-api/api 0.1.0 → 0.3.1

package/AGENT.md

@@ -0,0 +1,271 @@
+# API 编写规范
+
+## 目录结构
+
+API 文件应按照后端服务域名进行分组，文件路径与 API URL 路径保持一致。
+
+```
+src/
+├── sso/                    # sso.ccw.site 服务
+│   └── index.ts            # 导出该服务的所有 API
+├── community-web/          # community-web.ccw.site 服务
+│   └── index.ts
+├── index.ts                # 根导出
+└── types/                  # 公共类型定义
+```
+
+## 文件命名规范
+
+- 使用 `kebab-case`（短横线分隔）命名文件
+- 文件名应为 API endpoint名称，如 `login-by-password.ts`、`create-short-url.ts`
+- 测试文件命名为 `${功能}.test.ts`，放置在同一目录下
+
+## 代码结构规范
+
+每个 API 文件应遵循以下顺序：
+
+```typescript
+// 1. 导入依赖
+import { ccwAxios } from "@ccw-api/axios";
+import { ApiResponse, MongoDBId } from "types/api";
+
+// 2. 导出 URL（用于调试和测试）
+export const url = "https://domain.ccw.site/path/to/api";
+
+// 3. 请求类型定义 优先寻找已在types中定义的类型,oid studentId等key的类型固定为MongoDBId
+export type Req = {
+  field1: string;
+  field2: number;
+};
+
+// 4. 响应类型定义
+export type Res<T = any> = {
+  data: T;
+};
+
+// 5. 辅助类型或接口（如需要）
+export type ExtraInfo = {
+  detail: string;
+};
+
+// 6. JSDoc 注释
+/**
+ * API 功能描述
+ * @param {string} param1 参数1说明
+ * @param {number} param2 参数2说明
+ * @returns {Promise<Res>} 返回值说明
+ */
+
+// 7. 导出函数
+export async function apiFunctionName(
+  param1: string,
+  param2: number,
+): Promise<Res> {
+  const req: Req = { field1: param1, field2: param2 };
+  return await ccwAxios
+    .post<ApiResponse<Res>>(url, req)
+    .then((res) => res.data.body);
+}
+```
+
+## 类型定义规范
+
+### 通用类型
+
+项目提供以下公共类型，应优先使用：
+
+- `ApiResponse<T>` - 统一响应格式
+- `MongoDBId` - MongoDB ObjectID 类型
+- `CachedOssUrl` - OSS 缓存 URL 类型
+- `HexSecTimeStamp` - 十六进制秒级时间戳
+
+### 请求类型
+
+- 使用 `Req` 命名请求参数类型
+- 定义所有必填字段和可选字段
+- 使用字面量类型限制枚举值，如 `clientCode: "STUDY_COMMUNITY"`
+
+### 响应类型
+
+- 使用 `Res` 命名响应类型
+- 支持泛型参数以适应不同响应结构，如 `Res<Extra = string>`
+- 直接定义响应体结构，无需嵌套 `body`（由 `ApiResponse` 包装）
+
+## 函数编写规范
+
+### 参数处理
+
+- 函数参数应清晰命名，避免使用缩写
+- 将复杂对象参数拆分为多个简单参数，提高可读性
+- 提供合理的默认值，如 `reqExtra: ReqExtra = { device: "Node", browser: "Node.js" }`
+
+### 请求封装
+
+- 使用 `ccwAxios` 发送请求，不要直接使用 `axios`
+- 将请求体封装为 `Req` 类型变量后再发送
+- 使用 `satisfies Req` 确保请求体类型正确
+
+### 响应处理
+
+- 使用 `ApiResponse<T>` 包装响应类型
+- 通过 `.then((res) => res.data.body)` 直接返回响应体
+- 对于需要特殊处理的响应数据（如 JSON 解析），在函数内部完成
+
+## 导入规范
+
+### 统一导入方式
+
+```typescript
+// 正确 - 使用命名导入
+import { ccwAxios } from "@ccw-api/axios";
+
+// 错误 - 默认导入方式不一致
+import ccwAxios from "@ccw-api/axios";
+```
+
+### 类型导入
+
+```typescript
+// 正确 - 使用项目路径别名
+import { ApiResponse, MongoDBId } from "types/api";
+import { queryPage } from "src/queryPages";
+
+// 错误 - 相对路径不一致或太长
+import { ApiResponse } from "../../../types";
+```
+
+## 注释规范
+
+### JSDoc 注释
+
+所有导出函数必须添加 JSDoc 注释：
+
+```typescript
+/**
+ * 通过密码登录
+ * @param {string} loginKey 用户名
+ * @param {string} password 密码
+ * @param {ReqExtra} reqExtra 设备和浏览器信息（可选）
+ * @returns {Promise<Res<Extra>>} 登录结果
+ */
+export async function loginByPassword(
+  loginKey: string,
+  password: string,
+  reqExtra?: ReqExtra,
+): Promise<Res<Extra>> {
+  // ...
+}
+```
+
+### 类型注释
+
+对于复杂类型，添加适当的注释说明：
+如果该属性可能为url,请立即询问开发者
+
+```typescript
+export type ApprovalStatus<Tid extends number, Tn extends string> = {
+  /**
+   * 浮于iconLink之上的icon
+   */
+  mediumImage: CachedOssUrl;
+  /**
+   * 有时会包含tag的名称，如"Gandi开发者"
+   */
+  iconLink: CachedOssUrl;
+};
+```
+
+## 测试规范
+
+### 测试文件位置
+
+测试文件与 API 文件放在同一目录下，命名为 `${功能}.test.ts`。
+
+### 测试内容
+
+测试应覆盖：
+
+- 正常流程返回值验证
+- 异常情况错误信息验证
+- 参数边界情况
+
+```typescript
+import { getApprovalTags } from "./list";
+
+test("test approval list", async () => {
+  const tags = await getApprovalTags("63c2807d669fa967f17f5559");
+  expect(tags.find((v) => v.approvalTagId == 235).approvalTagName).toEqual(
+    "Gandi 开发者",
+  );
+});
+```
+
+## 导出规范
+
+### 服务入口导出
+
+每个服务目录（如 `sso/`、`community-web/`）应有 `index.ts`，统一导出该服务的所有 API：
+
+```typescript
+import { loginByPassword } from "./web/auth/login-by-password";
+import { logout } from "./web/auth/logout";
+
+export const sso = {
+  loginByPassword,
+  logout,
+};
+```
+
+### 根导出
+
+`src/index.ts` 导出所有服务：
+
+```typescript
+import { sso } from "./sso";
+import { communityWeb } from "./community-web";
+export type * from "./types";
+
+export { sso, communityWeb };
+
+export default {
+  sso,
+  communityWeb,
+};
+```
+
+## 错误处理
+
+- 使用 `@ccw-api/axios` 的拦截器自动处理错误
+- 测试时验证错误信息是否符合预期
+- 不要在 API 函数中捕获错误，让调用方处理
+
+## 最佳实践
+
+1. **URL 一致性**：`url` 常量应与实际 API 地址完全一致
+2. **类型安全**：使用 TypeScript 泛型提供灵活的类型支持
+3. **函数命名**：使用 `camelCase`，前缀描述操作（如 `get`, `create`, `login`）
+4. **单一职责**：每个文件只包含一个 API 函数
+5. **可测试性**：导出 `url` 常量便于测试和调试
+
+### 分页请求
+
+```typescript
+import { DEFAULT_PAGE_ARGS, queryPage } from "src/queryPages";
+
+// 其他一般请求配置
+
+export async function getDonatedRecordRanking(
+  args: any, // 其他参数
+  pageArgs_: Partial<PageArgs> = {},
+): Promise<Res> {
+  const pageArgs = {
+    ...DEFAULT_PAGE_ARGS,
+    ...pageArgs_,
+  };
+  const queryUrl = queryPage(url, pageArgs);
+  const req: Req = { ... }; // 构造请求
+  return await ccwAxios
+    .post<ApiResponse<Res>>(queryUrl, req)
+    .then((res) => res.data.body);
+}
+```

package/README.md

@@ -0,0 +1,324 @@
+# @ccw-api/api
+
+CCW（创作社区）前后端接口 SDK，整合 `sso.ccw.site` 与 `community-web.ccw.site`
+两大服务的常用 API，提供完整的 TypeScript 类型与开箱即用的分页封装。
+
+- 包格式：**ESM + CJS + .d.ts 三产物**同时产出
+- 类型：所有请求 / 响应字段**强类型**，后端 key 固定约束（如 `MongoDBId`、`CNameOssUrl`、`UUID`）
+- 分页：统一返回 `PagesRes<T>`（含 `totalNum` / `totalPages` / `sortField` 等元信息）
+
+---
+
+## 安装
+
+```bash
+npm install @ccw-api/api
+# 或
+pnpm add @ccw-api/api
+# 或
+yarn add @ccw-api/api
+```
+
+> 唯一运行时依赖：`@ccw-api/axios`（内置鉴权 header 注入的 axios 封装）。
+> `@ccw-api/api` 已将常用的 token 设置方法 **`setToken` 重新导出**，无需再单独依赖 axios 包。
+
+---
+
+## 快速开始
+
+### 1. 初始化 Token（前置条件）
+
+```ts
+import { setToken } from "@ccw-api/api";
+
+// 直接传入后端下发的 session token
+setToken("abcdefgfoo");
+```
+
+所有 `@ccw-api/api` 的方法都会复用同一个 axios 单例，**调用 API 时无需再传入鉴权参数**。
+
+### 2. 调用方式
+
+```ts
+import { sso, communityWeb } from "@ccw-api/api"; // ✅ 推荐：具名导入
+// 或
+import api from "@ccw-api/api"; // ✅ default 导入：api.sso / api.communityWeb
+```
+
+---
+
+## 模块一：SSO（sso.ccw.site）
+
+账号认证相关，共 3 个 API：
+
+```ts
+const { loginByPassword, logout, logoutBySession } = sso;
+
+// 账号密码登录
+await loginByPassword("student_number", "xxxxx", {
+  device: "WEB",
+  browser: "Chrome",
+});
+
+// 登出当前 session
+await logout();
+
+// 强制某个 session 下线用于登陆设备管理
+await logoutBySession("64...session_oid");
+```
+
+---
+
+## 模块二：Community-Web（community-web.ccw.site）
+
+覆盖作品 / 学生 / 星球 / 评论 / 通知 / 任务 / 表情 / 签到 / 云资产 / 学科专区 等业务领域，共 **68 个 API**。
+下面是常用场景示例。
+
+### 学生与作品
+
+```ts
+// 拉取学生档案
+const profile = await communityWeb.getStudentProfile(
+  "63c2807d669fa967f17f5559",
+);
+//   ^? StudentOverview（包含头像、简介、统计字段等）
+
+// 我的创作分
+const score = await communityWeb.getCreatorScore();
+console.log(score.rank); // "ORDINARY" | "HACKER" | "ADVANCED"
+
+// 分页拉取某学生的作品列表（含 totalNum / totalPages）
+const creations = await communityWeb.getCreationsByStudent(
+  "63c2807d669fa967f17f5559",
+  { page: 1, perPage: 12, sortField: "createdAt", sortType: "DESC" },
+);
+// creations: PagesRes<CreationSimple>
+console.log(creations.totalNum, creations.data[0].title);
+```
+
+### 星球（HashTag）与作品关联
+
+```ts
+// 查询某作品加入了哪些星球
+const planets = await communityWeb.getPlanetsOfCreation(
+  "69929185f8d6142487fd4b2e",
+);
+// planets: HashTagCreationRelation[]
+// planets[0].rank  →  "ORDINARY"（星球审核等级，与创作分 CreatorScore.rank 概念不同）
+
+// 查询我加入某星球的作品分页（排除一个星球 + 过滤状态）
+const mine = await communityWeb.getMyHashTagCreations(
+  "蔚蓝档案",
+  ["PUBLISHED"],
+  { page: 1, perPage: 8, sortField: "lastPassedAt", sortType: "DESC" },
+);
+```
+
+### 通知（细化了 15 种 contentCategory）
+
+```ts
+import type {
+  NotificationContent,
+  PostCommentContent,
+  FollowedContent,
+} from "@ccw-api/api";
+
+const page = await communityWeb.getNotificationPage("COMMENT_TO_ME", {
+  page: 1,
+  perPage: 20,
+});
+// page.data[].content  类型是 NotificationContent（判别联合）
+// 用 contentCategory 做类型收窄：
+
+for (const notif of page.data) {
+  switch (notif.contentCategory) {
+    case "POST_COMMENT": {
+      const c = notif.content as PostCommentContent;
+      console.log("评论者:", c.sender, "文章:", c.subject_outline);
+      break;
+    }
+    case "FOLLOWED": {
+      const c = notif.content as FollowedContent;
+      console.log("新粉丝:", c.sender, c.sender_id);
+      break;
+    }
+    case "CREATION_SHARE":
+    case "SESSION_CREATED":
+    case "COMMUNITY_ACTIVITY":
+    case "POST_VISIBILITY_CHANGED":
+    // ……共 15 种，可按 IDE 补全逐项处理
+  }
+}
+
+// 拉取所有分组的未读统计
+const stats = await communityWeb.getNotificationStats();
+// stats.creationInteraction  stats.commentToMe  stats.followMe ……
+```
+
+### 任务、表情、金币、签到
+
+```ts
+// 我的任务列表
+const tasks = await communityWeb.getMyTasks();
+
+// 领取某个任务奖励
+await communityWeb.acceptAward("61273ccf1730f4308e853f6a");
+
+// 个人金币余额（充值 / 赠送 / 提现 三栏分离）
+const coin = await communityWeb.getPersonalCurrencyAccount();
+// coin: { internalCurrencyBalance, topUpCurrencyBalance, withdrawCurrencyBalance }
+
+// 全部表情包 + 分页 + 分类
+const [allEmoji, emojiPage, categories] = await Promise.all([
+  communityWeb.getAllEmojis(),
+  communityWeb.getEmojiPage("ENABLED", { page: 1, perPage: 50 }),
+  communityWeb.getEmojiCategoryList(),
+]);
+
+// 签到
+await communityWeb.insertCheckInRecord(); // 今日打卡
+const history = await communityWeb.getCheckInRecords();
+```
+
+### 黑名单、封禁、禁言查询
+
+```ts
+const STUDENT = "63c2807d669fa967f17f5559";
+
+// 轻量：是否拉黑（只返回 NOT_BLOCKED / BLOCKING）
+const s = await communityWeb.getStudentBlockStatus(STUDENT);
+
+// 详细：完整的 BlockActionRecord（拉黑动作记录，oid / createdAt / fromEntityId）
+const detail = await communityWeb.getStudentBlockRecordDetail(STUDENT);
+
+// 封禁详情（带泛型，locked=false 时其他字段全为 null）
+const locked = await communityWeb.getLockedUserDetail<true>(
+  "642c0e8a59230841adf62406",
+);
+
+// 禁言详情（studentNumber 是 244373873 这种数字字符串，null 表示未禁言）
+const muted = await communityWeb.getMutedUserDetail("244373873");
+```
+
+### 通用工具型 API
+
+```ts
+// 生成短链
+await communityWeb.createShortUrl("https://ccw.site/detail/xxx");
+
+// 生成邀请码（api/v1/short_code/encode）
+await communityWeb.encodeShortCode("hello world", 1, 6);
+
+// 服务器时间
+await communityWeb.getTime();
+
+// 埋点事件上报
+await communityWeb.sendEvent("creation_detail_view_6880873d2211fa69e41c9d19");
+
+// 广告横幅
+await communityWeb.getLeafletsItemList(1001);
+
+// 学科专区（分页 / 按频道）
+await communityWeb.getSubjectAreaPage({ page: 1, perPage: 20 });
+await communityWeb.getSubjectAreaPageByChannel("PRIMARY");
+```
+
+---
+
+## 类型系统
+
+### 原语类型（`types/api.d.ts`）
+
+可直接从包顶层作为 `type` 导入：
+
+```ts
+import type {
+  MongoDBId, // 24 位 hex 字符串（ObjectId）
+  CNameOssUrl, // https://m.ccw.site/... 或 https://m.xiguacity.cn/... OSS URL
+  UUID, // `${string}-${string}-${string}-${string}-${string}` 类型体操
+  ApiResponse, // { code, msg, body: T } 后端统一响应壳（SDK 内部已拆）
+} from "@ccw-api/api";
+```
+
+### 领域命名空间
+
+每个 `types/*.d.ts` 作为一个命名空间重新导出，**避免同名类型冲突**（典型如 `Student` vs `StudentOverview` vs `Account.Types.Student`）：
+
+```ts
+import type {
+  Api, // 原语类型（MongoDBId / CNameOssUrl / UUID / ApiResponse ...）
+  UserData, // Student / StudentOverview / CreatorScore / UserCard ...
+  Creation, // Creation / HashTag / HashTagCreationRank / CreationRelease ...
+  Comment, // Comment / CommentStatus ...
+  Notification, // Notification / NotificationSenderInfo / NotificationGroup ...
+  NotificationContent, // 15 种通知 content 判别联合
+  Pages, // PageArgs / PagesRes
+  Session, // StudentSession / SessionArea
+  Account, // AccountTypes
+  Approval, // ApprovalTag
+} from "@ccw-api/api";
+
+type Score = UserData.CreatorScore["rank"]; // "ORDINARY" | "HACKER" | "ADVANCED"
+type PlanetRank = Creation.HashTagCreationRank; // "ORDINARY"
+```
+
+---
+
+## 分页约定
+
+所有分页 API 都遵循同一套形状（详见 `types/pages.d.ts` + `src/queryPages.ts`）：
+
+```ts
+import type { PageArgs, PagesRes } from "@ccw-api/api";
+
+// 入参 Partial<PageArgs<SortField>>，默认 { page:1, perPage:20, sortType:"DESC" }
+// 出参 PagesRes<T> 完整结构：
+const p: PagesRes<Creation.Creation> = {
+  data: [], // 当前页数据
+  page: 1,
+  perPage: 20,
+  offset: 0,
+  totalNum: 1234, // 总条数 —— 之前版本被截断，目前 SDK 已完整透出
+  totalPages: 62, // 总页数
+  sortField: "createdAt",
+  sortType: "DESC",
+};
+```
+
+---
+
+## 开发 & 发布
+
+```bash
+# 三产物构建（node / esm / .d.ts）
+npm run build
+
+# 跑测试（Jest 30 + ts-jest，67 suites / 72 tests）
+npm test
+npm run test:dev       # watch 模式
+
+# 文档（TypeDoc，生成到 doc/ 或默认输出目录）
+npm run doc
+npm run doc:dev
+```
+
+`npm publish` 会自动触发 `prepublishOnly` → **build + test** 全跑一遍，失败会阻断发布。
+
+---
+
+## 目录与规范
+
+所有 API 文件严格遵循 `AGENT.md` 规范：
+
+- **按域名分组**：`src/sso` / `src/community-web`，内部子目录对应 URL 路径
+- **单文件单接口**：文件名 `kebab-case`，对应 endpoint 最后一段
+- **7 段式模板**（每个 API 文件内部固定顺序）：
+  1. `import`
+  2. `export const url = "https://..."`（调试 & 测试直接引用）
+  3. `export type Req = { ... }`
+  4. `export type Res = { ... }`（响应体内部，不含 `ApiResponse` 外层）
+  5. 辅助类型
+  6. JSDoc（`@param` / `@returns`）
+  7. `export async function xxx(): Promise<Res>`
+
+新增 API 时，**最后记得在 `src/community-web/index.ts` 里 `import + 对象字面量聚合导出`**，否则外部访问不到。

package/dist/esm/community-web/api/v1/short_code/encode.js

@@ -0,0 +1,25 @@
+import { ccwAxios } from "@ccw-api/axios";
+export const url = "https://community-web.ccw.site/api/v1/short_code/encode";
+/**
+ * 生成作品邀请码
+ * @param {MongoDBId} inviterId 邀请人id
+ * @param {CachedOssUrl} inviterAvatar 邀请人头像
+ * @param {string} inviterName 邀请人用户名
+ * @param {MongoDBId} creationOid 作品id
+ * @returns {Promise<Res>}
+ */
+export async function encodeShortCode(inviterId, inviterAvatar, inviterName, creationOid) {
+    const req = {
+        origin: {
+            inviterAvatar,
+            inviterName,
+            inviterId,
+            inviterType: "STUDENT",
+            entrance: "create_detail",
+            creationOid,
+        },
+    };
+    return await ccwAxios
+        .post(url, req)
+        .then((res) => res.data.body);
+}

package/dist/esm/community-web/api/v1/short_code/shortcode.test.js

@@ -0,0 +1,5 @@
+import { encodeShortCode } from "./encode";
+test("test shortcode", async () => {
+    const res = await encodeShortCode("63c2807d669fa967f17f5559", "https://m.ccw.site/user_projects_assets/244373873/3fc7886d05aed9f369d2c0bb2d677fc0.jpeg", "孟夫子驾到", "6386e11cfc1ed14684de07f8");
+    expect(res.code).toHaveLength("yZdXmD3PvwVPA30W".length);
+});

package/dist/esm/community-web/approval/approval.test.js

@@ -0,0 +1,5 @@
+import { getApprovalTags } from "./list";
+test("test approval list", async () => {
+    const tags = await getApprovalTags("63c2807d669fa967f17f5559");
+    expect(tags.find((v) => v.approvalTagId == 235).approvalTagName).toEqual("Gandi 开发者");
+});

package/dist/esm/community-web/approval/list.js

@@ -0,0 +1,16 @@
+import ccwAxios from "@ccw-api/axios";
+export const url = "https://community-web.ccw.site/approval/list";
+/**
+ * 获取特定用户的勋章数据
+ * @param {MongoDBId} studentOid 用户id
+ * @returns {Promise<Res<Tid, Tn>>} 勋章数据
+ */
+export async function getApprovalTags(studentOid) {
+    const req = {
+        objectId: studentOid,
+        objectType: "STUDENT",
+    };
+    return await ccwAxios
+        .post(url, req)
+        .then((res) => res.data.body);
+}

package/dist/esm/community-web/base/dateTime.js

@@ -0,0 +1,10 @@
+import ccwAxios from "@ccw-api/axios";
+export const url = "https://community-web.ccw.site/base/dateTime";
+/**
+ * @returns {Promise<number>} 当前时间戳,相当于Date.now()
+ */
+export async function getTime() {
+    return ccwAxios
+        .post(url, undefined)
+        .then((res) => res.data.body);
+}

package/dist/esm/community-web/base/dateTime.test.js

@@ -0,0 +1,6 @@
+import { getTime } from "../base/dateTime";
+test("get time should return a number", async () => {
+    const time = await getTime();
+    expect(typeof time).toBe("number");
+    expect(time).toBeGreaterThan(0);
+});

package/dist/esm/community-web/campaign_resource/detail.js

@@ -0,0 +1,12 @@
+import { ccwAxios } from "@ccw-api/axios";
+export const url = "https://community-web.ccw.site/campaign_resource/detail";
+/**
+ * 不知道这个接口有什么用,请查看https://www.ccw.site/pages/tags自行寻找用法
+ * @param {K} keyword 活动关键词
+ * @returns {Promise<Res<K>>}
+ */
+export async function getCampaignResources(keyword) {
+    return await ccwAxios
+        .post(url, { keyword })
+        .then((res) => res.data.body);
+}

package/dist/esm/community-web/campaign_resource/detail.test.js

@@ -0,0 +1,10 @@
+import { getCampaignResources } from "./detail";
+test("get campaign resources with tags keyword", async () => {
+    const res = await getCampaignResources("tags");
+    expect(res.keyword).toBe("tags");
+    expect(res.resourceType).toBe("SUBJECT_AREA");
+});
+test("get campaign resources with mmo keyword", async () => {
+    const res = await getCampaignResources("mmo");
+    expect(res.keyword).toBe("mmo");
+});