@kevisual/cnb 0.0.57 → 0.0.59

package/src/org/index.ts

@@ -0,0 +1,574 @@
+/**
+ * @title 组织管理模块
+ * @description 提供组织（Organizations）的管理功能，包括创建、更新、删除组织，获取组织列表、子组织、组织设置等
+ * @tags organization, group, team, cnb, api
+ * @createdAt 2025-12-04
+ */
+
+import { CNBCore, CNBCoreOptions } from "../cnb-core.ts";
+import { Result } from "@kevisual/query";
+
+/**
+ * 组织角色枚举
+ */
+export enum AccessRole {
+  Guest = "Guest",
+  Reporter = "Reporter",
+  Developer = "Developer",
+  Master = "Master",
+  Owner = "Owner",
+}
+
+/**
+ * 组织设置值枚举
+ */
+export enum SettingValue {
+  /** 关闭组织介绍页 */
+  DisableOrganizationReadme = "disable_organization_readme",
+  /** 仅可使用云原生开发 */
+  CloudNativeDevOnly = "cloud_native_dev_only",
+  /** 支持重写分支保护规则 */
+  UseRootGroupBranchProtectionOnly = "user_root_group_branch_protection_only",
+  /** 禁止仓库修改保护分支规则 */
+  ForbidRedefineBranchProtection = "forbid_redefine_branch_protection",
+  /** 允许 TAPD 访问组织资源 */
+  EnableTAPDAccess = "enable_tapd_access",
+  /** 私有任务集显示水印 */
+  EnableShowPrivateMissionWaterMark = "enable_show_private_mission_water_mark",
+  /** 禁止创建组织 */
+  PreventOrganizationCreation = "prevent_organization_creation",
+  /** 禁止创建仓库 */
+  PreventRepositoryCreation = "prevent_repository_creation",
+  /** 禁止创建任务集 */
+  PreventMissionCreation = "prevent_mission_creation",
+  /** 禁止创建制品库 */
+  PreventRegistryCreation = "prevent_registry_creation",
+  /** 禁止邀请成员 */
+  DisableInvitation = "disable_invitation",
+  /** 禁止修改资源可见性 */
+  PreventVisibilityModification = "prevent_visibility_modification",
+  /** 禁止删除资源 */
+  PreventResourceDeletion = "prevent_resource_deletion",
+  /** 禁止归档仓库 */
+  PreventRepositoryArchival = "prevent_repository_archival",
+  /** 禁止转移组织 */
+  PreventOrganizationTransfer = "prevent_organization_transfer",
+  /** 禁止转移仓库 */
+  PreventRepositoryTransfer = "prevent_repository_transfer",
+  /** 禁止转移任务集 */
+  PreventMissionTransfer = "prevent_mission_transfer",
+  /** 禁止转移制品库 */
+  PreventRegistryTransfer = "prevent_registry_transfer",
+  /** 使用组织仓库配额 */
+  UseGroupGitQuota = "use_group_git_quota",
+  /** 使用组织仓库对象限制 */
+  UseGroupGitObjectLimit = "use_group_git_object_limit",
+  /** 仅根组织管理员可添加成员 */
+  EnableAddMemberOnlyRoot = "enable_add_member_only_root",
+  /** 开启根组织推送限制选项 */
+  UseRootGroupGitPushLimit = "use_root_group_git_push_limit",
+  /** 允许子组织管理员添加成员 */
+  EnableAddMember = "enable_add_member",
+  /** 仅根组织管理员可修改成员角色 */
+  EnableChangeMemberRoleOnlyRoot = "enable_change_member_role_only_root",
+}
+
+/**
+ * 创建组织请求参数
+ */
+export interface CreateGroupParams {
+  /** 组织路径 */
+  path: string;
+  /** 组织描述 */
+  description?: string;
+  /** 根组织绑定的域名 */
+  bind_domain?: string;
+  /** 备注 */
+  remark?: string;
+}
+
+/**
+ * 更新组织信息请求参数
+ */
+export interface UpdateGroupParams {
+  /** 组织描述 */
+  description?: string;
+  /** 组织展示名称 */
+  remark?: string;
+  /** 组织网站 */
+  site?: string;
+  /** 组织联系邮箱 */
+  email?: string;
+  /** 绑定的域名 */
+  domain?: string;
+  /** 微信公众号 */
+  wechat_mp?: string;
+  /** README 仓库 ID */
+  readme_repo_id?: number;
+  /** README 仓库路径 */
+  readme_repo_path?: string;
+}
+
+/**
+ * 转移组织请求参数
+ */
+export interface TransferGroupParams {
+  /** 源组织路径 */
+  source: string;
+  /** 目标组织路径 */
+  target: string;
+}
+
+/**
+ * 上传 Logo 请求参数
+ */
+export interface UploadLogoParams {
+  /** 文件名 */
+  name: string;
+  /** 文件大小（字节） */
+  size: number;
+  /** 额外参数 */
+  ext?: Record<string, string>;
+}
+
+/**
+ * 更新组织设置请求参数
+ */
+export interface UpdateGroupSettingParams {
+  /** 是否对外隐藏组织成员，0 - 否, 1 - 是 */
+  hide_members?: number;
+  /** 是否对外隐藏子组织，0 - 否, 1 - 是 */
+  hide_sub_groups?: number;
+  /** 是否对外显示私有仓库水印，0 - 否, 1 - 是 */
+  show_private_repo_watermark?: number;
+  /** 组织保护开关，0 - 关闭，1 - 打开 */
+  group_protection?: number;
+  /** 组织限制指定邮箱认证才能加入 */
+  email_verification?: string[];
+  /** 组织设置值，多个选项用逗号拼接 */
+  values?: string;
+}
+
+/**
+ * 组织信息（包含访问权限）
+ */
+export interface OrganizationAccess {
+  /** 用户在当前资源的最大权限 */
+  access_role?: AccessRole;
+  /** 所有层级成员总数 */
+  all_member_count?: number;
+  /** 所有层级子组织数量 */
+  all_sub_group_count?: number;
+  /** 所有层级子任务数量 */
+  all_sub_mission_count?: number;
+  /** 所有层级制品库数量 */
+  all_sub_registry_count?: number;
+  /** 所有层级仓库数量 */
+  all_sub_repo_count?: number;
+  /** 创建时间 */
+  created_at?: string;
+  /** 组织描述 */
+  description?: string;
+  /** 绑定的域名 */
+  domain?: string;
+  /** 组织邮箱 */
+  email?: string;
+  /** 关注数量 */
+  follow_count?: number;
+  /** 是否冻结 */
+  freeze?: boolean;
+  /** 是否有子组织 */
+  has_sub_group?: boolean;
+  /** 组织 ID */
+  id?: string;
+  /** 直接成员数量 */
+  member_count?: number;
+  /** 组织展示名称 */
+  name?: string;
+  /** 组织路径 */
+  path?: string;
+  /** 是否置顶 */
+  pinned?: boolean;
+  /** 置顶时间 */
+  pinned_time?: string;
+  /** README 仓库路径 */
+  readme_repo_path?: string;
+  /** 备注 */
+  remark?: string;
+  /** 组织网站 */
+  site?: string;
+  /** 下一级子组织数量 */
+  sub_group_count?: number;
+  /** 下一级子任务数量 */
+  sub_mission_count?: number;
+  /** 下一级制品库数量 */
+  sub_registry_count?: number;
+  /** 下一级仓库数量 */
+  sub_repo_count?: number;
+  /** 更新时间 */
+  updated_at?: string;
+  /** 微信公众号 */
+  wechat_mp?: string;
+}
+
+/**
+ * 组织信息（联合类型）
+ */
+export interface OrganizationUnion {
+  /** 所有层级成员总数 */
+  all_member_count?: number;
+  /** 所有层级子组织数量 */
+  all_sub_group_count?: number;
+  /** 所有层级子任务数量 */
+  all_sub_mission_count?: number;
+  /** 所有层级制品库数量 */
+  all_sub_registry_count?: number;
+  /** 所有层级仓库数量 */
+  all_sub_repo_count?: number;
+  /** 创建时间 */
+  created_at?: string;
+  /** 组织描述 */
+  description?: string;
+  /** 绑定的域名 */
+  domain?: string;
+  /** 组织邮箱 */
+  email?: string;
+  /** 关注数量 */
+  follow_count?: number;
+  /** 是否冻结 */
+  freeze?: boolean;
+  /** 是否有子组织 */
+  has_sub_group?: boolean;
+  /** 组织 ID */
+  id?: string;
+  /** 直接成员数量 */
+  member_count?: number;
+  /** 组织展示名称 */
+  name?: string;
+  /** 组织路径 */
+  path?: string;
+  /** 是否置顶 */
+  pinned?: boolean;
+  /** 置顶时间 */
+  pinned_time?: string;
+  /** README 仓库路径 */
+  readme_repo_path?: string;
+  /** 备注 */
+  remark?: string;
+  /** 组织网站 */
+  site?: string;
+  /** 下一级子组织数量 */
+  sub_group_count?: number;
+  /** 下一级子任务数量 */
+  sub_mission_count?: number;
+  /** 下一级制品库数量 */
+  sub_registry_count?: number;
+  /** 下一级仓库数量 */
+  sub_repo_count?: number;
+  /** 更新时间 */
+  updated_at?: string;
+  /** 微信公众号 */
+  wechat_mp?: string;
+}
+
+/**
+ * 上传 Logo 响应
+ */
+export interface UploadLogoResponse {
+  /** 上传后的文件信息 */
+  assets?: {
+    /** 文件大小 */
+    size?: number;
+    /** 文件名 */
+    name?: string;
+    /** 文件路径 */
+    path?: string;
+    /** 内容类型 */
+    content_type?: string;
+    /** 额外信息 */
+    ext?: Record<string, string>;
+  };
+  /** 上传表单字段 */
+  form?: Record<string, string>;
+  /** 上传 URL */
+  upload_url?: string;
+  /** 后续确认接口使用的 token */
+  token?: string;
+}
+
+/**
+ * 组织设置值
+ */
+export interface SettingValues {
+  /** 禁用组织 README */
+  disable_organization_readme?: boolean;
+  /** 云原生开发限制 */
+  cloud_native_dev_only?: boolean;
+  /** 根组织分支保护规则限制 */
+  user_root_group_branch_protection_only?: boolean;
+  /** 禁止重定义分支保护 */
+  forbid_redefine_branch_protection?: boolean;
+  /** TAPD 访问 */
+  enable_tapd_access?: boolean;
+  /** 私有任务水印 */
+  enable_show_private_mission_water_mark?: boolean;
+  /** 禁止组织创建 */
+  prevent_organization_creation?: boolean;
+  /** 禁止仓库创建 */
+  prevent_repository_creation?: boolean;
+  /** 禁止任务集创建 */
+  prevent_mission_creation?: boolean;
+  /** 禁止制品库创建 */
+  prevent_registry_creation?: boolean;
+  /** 禁止邀请 */
+  disable_invitation?: boolean;
+  /** 禁止可见性修改 */
+  prevent_visibility_modification?: boolean;
+  /** 禁止资源删除 */
+  prevent_resource_deletion?: boolean;
+  /** 禁止仓库归档 */
+  prevent_repository_archival?: boolean;
+  /** 禁止组织转移 */
+  prevent_organization_transfer?: boolean;
+  /** 禁止仓库转移 */
+  prevent_repository_transfer?: boolean;
+  /** 禁止任务集转移 */
+  prevent_mission_transfer?: boolean;
+  /** 禁止制品库转移 */
+  prevent_registry_transfer?: boolean;
+  /** 使用组织 Git 配额 */
+  use_group_git_quota?: boolean;
+  /** 使用组织 Git 对象限制 */
+  use_group_git_object_limit?: boolean;
+  /** 仅根组织可添加成员 */
+  enable_add_member_only_root?: boolean;
+  /** 使用根组织 Git 推送限制 */
+  use_root_group_git_push_limit?: boolean;
+  /** 允许添加成员 */
+  enable_add_member?: boolean;
+  /** 仅根组织可修改成员角色 */
+  enable_change_member_role_only_root?: boolean;
+}
+
+/**
+ * 组织设置信息（包含父级继承）
+ */
+export interface OrganizationSettingWithParent {
+  /** 上级是否隐藏成员，true - 上级禁止显示 */
+  can_show_members?: boolean;
+  /** 上级是否隐藏子组织，true - 上级禁止显示 */
+  can_show_sub_groups?: boolean;
+  /** 是否可以显示水印 */
+  can_show_watermark?: boolean;
+  /** 邮箱验证配置 */
+  email_verification?: string[];
+  /** 组织保护开关 */
+  group_protection?: number;
+  /** 是否对外隐藏组织成员，0 - 否, 1 - 是 */
+  hide_members?: number;
+  /** 是否对外隐藏子组织，0 - 否, 1 - 是 */
+  hide_sub_groups?: number;
+  /** 根组织邮箱验证配置 */
+  root_email_verification?: string[];
+  /** 根组织保护开关 */
+  root_group_protection?: boolean;
+  /** 根组织设置值 */
+  root_values?: SettingValues;
+  /** 是否对外显示私有仓库水印 */
+  show_private_repo_watermark?: number;
+  /** 当前组织设置值 */
+  values?: SettingValues;
+}
+
+/**
+ * 组织管理模块
+ * https://api.cnb.cool/#/operations/GetGroup
+ */
+export class Organization extends CNBCore {
+  constructor(options: CNBCoreOptions) {
+    super(options);
+  }
+
+  /**
+   * 创建新组织
+   * @param params 组织信息
+   */
+  create(params: CreateGroupParams): Promise<Result<OrganizationAccess>> {
+    return this.post({
+      url: "/groups",
+      data: params,
+    });
+  }
+
+  /**
+   * 获取当前用户拥有权限的顶层组织列表
+   * @param params 查询参数
+   */
+  listTopGroups(params?: {
+    page?: number;
+    page_size?: number;
+    search?: string;
+    role?: AccessRole;
+  }): Promise<Result<OrganizationAccess[]>> {
+    return this.get({
+      url: "/user/groups",
+      params,
+    });
+  }
+
+  /**
+   * 查询当前用户在指定组织下拥有指定权限的子组织列表
+   * @param slug 组织路径
+   * @param params 查询参数
+   */
+  listGroups(
+    slug: string,
+    params?: {
+      page?: number;
+      page_size?: number;
+      access?: number;
+    }
+  ): Promise<Result<OrganizationAccess[]>> {
+    return this.get({
+      url: `/user/groups/${slug}`,
+      params,
+    });
+  }
+
+  /**
+   * 获取指定用户拥有权限的顶层组织列表
+   * @param username 用户名
+   * @param params 查询参数
+   */
+  getGroupsByUsername(
+    username: string,
+    params?: {
+      search?: string;
+      page?: number;
+      page_size?: number;
+    }
+  ): Promise<Result<OrganizationUnion>> {
+    return this.get({
+      url: `/users/${username}/groups`,
+      params,
+    });
+  }
+
+  /**
+   * 获取指定组织信息
+   * @param group 组织路径
+   */
+  getGroup(group: string): Promise<Result<OrganizationAccess>> {
+    return this.get({
+      url: `/${group}`,
+    });
+  }
+
+  /**
+   * 更新组织信息，可更新的内容为：组织描述、组织展示名称、组织网站、组织联系邮箱
+   * @param group 组织路径
+   * @param params 更新内容
+   */
+  updateGroup(
+    group: string,
+    params: UpdateGroupParams
+  ): Promise<Result<OrganizationAccess>> {
+    return this.put({
+      url: `/${group}`,
+      data: params,
+    });
+  }
+
+  /**
+   * 删除指定组织
+   * @param group 组织路径
+   * @param identityTicket 微信身份验证票据
+   */
+  deleteGroup(
+    group: string,
+    identityTicket?: string
+  ): Promise<Result<void>> {
+    return this.delete({
+      url: `/${group}`,
+      headers: identityTicket
+        ? { "x-cnb-identity-ticket": identityTicket }
+        : undefined,
+    });
+  }
+
+  /**
+   * 转移组织
+   * @param group 组织路径
+   * @param params 转移参数
+   */
+  transfer(
+    group: string,
+    params: TransferGroupParams
+  ): Promise<Result<void>> {
+    return this.post({
+      url: `/${group}/-/transfer`,
+      data: params,
+    });
+  }
+
+  /**
+   * 上传 Logo，发起上传请求，返回上传文件的 URL，请使用 PUT 发起流式上传
+   * @param group 组织路径
+   * @param params 上传参数
+   */
+  uploadLogo(
+    group: string,
+    params: UploadLogoParams
+  ): Promise<Result<UploadLogoResponse>> {
+    return this.post({
+      url: `/${group}/-/upload/logos`,
+      data: params,
+    });
+  }
+
+  /**
+   * 获取指定组织的配置详情
+   * @param slug 组织路径
+   */
+  getSetting(
+    slug: string
+  ): Promise<Result<OrganizationSettingWithParent>> {
+    return this.get({
+      url: `/${slug}/-/settings`,
+    });
+  }
+
+  /**
+   * 更新指定组织的配置
+   * @param slug 组织路径
+   * @param params 设置参数
+   */
+  updateSetting(
+    slug: string,
+    params: UpdateGroupSettingParams
+  ): Promise<Result<void>> {
+    return this.put({
+      url: `/${slug}/-/settings`,
+      data: params,
+    });
+  }
+
+  /**
+   * 获取指定组织下的子组织列表
+   * @param slug 组织路径
+   * @param params 查询参数
+   */
+  listSubgroups(
+    slug: string,
+    params?: {
+      search?: string;
+      page?: number;
+      page_size?: number;
+    }
+  ): Promise<Result<OrganizationUnion[]>> {
+    return this.get({
+      url: `/${slug}/-/sub-groups`,
+      params,
+    });
+  }
+}