@ccw-api/api 0.3.0 → 0.4.0

package/dist/types/types/notificationContent.d.ts

@@ -0,0 +1,126 @@
+import { CNameOssUrl, MongoDBId, UUID } from "./api";
+export type SubjectType = "POST" | "CREATION" | "EXTENSION" | "PROFILE" | "SOCIETY" | "ACTIVITY" | string;
+export type ContentCategory = "POST_LIKED" | "POST_FAVORITE" | "POST_COMMENT" | "CREATION_LIKED" | "CREATION_FAVORITE" | "CREATION_COMMENTED" | "CREATION_SHARE" | "EXTENSION_LIKED" | "EXTENSION_COMMENTED" | "EXTENSION_COMMENT_REPLIED" | "PROFILE_LEAVE_WORDS" | "SESSION_CREATED" | "COMMUNITY_ACTIVITY" | "FOLLOWED" | "POST_VISIBILITY_CHANGED" | string;
+export interface PostNotificationContentBase {
+    subject_type: "POST";
+    sender: string;
+    subject_oid: MongoDBId;
+    subject_outline: string;
+    avatar: null;
+    sender_id: MongoDBId;
+    slug: UUID;
+}
+export interface PostLikedContent extends PostNotificationContentBase {
+}
+export interface PostFavContent extends PostNotificationContentBase {
+    comments: string;
+}
+export interface PostCommentContent {
+    ext: {
+        slug: UUID;
+    } | null;
+    comments: string;
+    subject_type: "POST";
+    sender: string;
+    subject_oid: MongoDBId;
+    subject_outline: string;
+    senderType: "STUDENT" | string;
+    avatar: CNameOssUrl;
+    message: string | null;
+    sender_id: MongoDBId;
+}
+export interface CreationNotificationContentBase {
+    subject_type: "CREATION";
+    sender: string;
+    subject_oid: MongoDBId;
+    sender_id: MongoDBId;
+}
+export interface CreationLikeNotificationContent extends CreationNotificationContentBase {
+    homework_title: string;
+    homework_id: MongoDBId;
+    student_id: `${number}`;
+    avatar: CNameOssUrl;
+    like_icon: CNameOssUrl;
+}
+export interface CreationFavContent extends CreationNotificationContentBase {
+    comments: string;
+    subject_outline: string;
+}
+export interface CreationCommentedContent {
+    ext: null;
+    comments: string;
+    subject_type: "CREATION";
+    sender: string;
+    subject_oid: MongoDBId;
+    subject_outline: string;
+    senderType: "STUDENT" | string;
+    avatar: CNameOssUrl;
+    message: string | null;
+    sender_id: MongoDBId;
+}
+export interface CreationShareContent {
+    subject_type: "CREATION";
+    subject_outline: string;
+    subject_oid: MongoDBId;
+    sender_id: MongoDBId;
+}
+export interface ExtensionLikedContent {
+    subject_type: "EXTENSION";
+    sender: string;
+    subject_oid: string;
+    subject_outline: string;
+    avatar: null;
+    sender_id: MongoDBId;
+}
+export interface ExtensionCommentedContent {
+    ext: {
+        target: MongoDBId;
+    } | null;
+    comments: string;
+    subject_type: "EXTENSION";
+    sender: string;
+    subject_oid: string;
+    subject_outline: string;
+    senderType: "STUDENT" | string;
+    avatar: CNameOssUrl;
+    message: string | null;
+    sender_id: MongoDBId;
+}
+export interface ExtensionCommentRepliedContent extends ExtensionCommentedContent {
+}
+export interface ProfileLeaveWordsContent {
+    ext: null;
+    comments: string;
+    subject_type: "PROFILE";
+    sender: string;
+    subject_oid: MongoDBId;
+    subject_outline: string;
+    senderType: "STUDENT" | string;
+    avatar: CNameOssUrl;
+    message: string | null;
+    sender_id: MongoDBId;
+}
+export interface SessionCreatedContent {
+    comments: string;
+    subject_type: "SOCIETY";
+    subject_oid: null;
+}
+export interface CommunityActivityContent {
+    comments: string;
+    subject_type: "ACTIVITY";
+    subject_oid: MongoDBId;
+    subject_outline: string;
+}
+export interface FollowedContent {
+    comments: string;
+    subject_type: "SOCIETY";
+    sender: string;
+    subject_oid: MongoDBId;
+    sender_id: MongoDBId;
+}
+export interface PostVisibilityChangedContent {
+    comments: string;
+    subject_type: "SOCIETY";
+    subject_oid: null;
+}
+export type NotificationContent = PostLikedContent | PostFavContent | PostCommentContent | CreationLikeNotificationContent | CreationFavContent | CreationCommentedContent | CreationShareContent | ExtensionLikedContent | ExtensionCommentedContent | ExtensionCommentRepliedContent | ProfileLeaveWordsContent | SessionCreatedContent | CommunityActivityContent | FollowedContent | PostVisibilityChangedContent | Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccw-api/api",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "ccw api collections",
   "license": "MIT",
   "author": "Meng Fuzi",
@@ -16,6 +16,10 @@
       "require": "./dist/node/index.js"
     }
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "prepublishOnly": "npm run build && npm test",
     "test": "jest",
@@ -31,6 +35,7 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^26.0.1",
     "jest": "^30.4.2",
+    "prettier-plugin-sort-members": "^0.2.4",
     "ts-jest": "^29.4.11",
     "typedoc": "^0.28.19"
   }

package/AGENT.md

@@ -1,271 +0,0 @@
-# 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);
-}
-```