@lark-apaas/auth-sdk 0.1.0-alpha.6 → 0.1.0-alpha.7

package/README.md

@@ -1,8 +1,8 @@
-## @lark-apaas/auth-sdk
+# @lark-apaas/auth-sdk
 
 基于 CASL 的前端鉴权 SDK，封装了权限数据获取、Ability 初始化与 React 集成，帮助你在应用中便捷地做「功能级/按钮级/菜单级/页面级」的权限控制。
 
-### 安装
+## 安装
 
 ```bash
 npm i @lark-apaas/auth-sdk
@@ -10,7 +10,7 @@ npm i @lark-apaas/auth-sdk
 yarn add @lark-apaas/auth-sdk
 ```
 
-### 快速开始
+## 快速开始
 
 ```tsx
 import React from 'react';
@@ -50,13 +50,14 @@ function Home() {
 ## 核心 API
 
 ### AuthProvider
+
 - **作用**: 提供 `Ability` 与权限状态上下文，自动/手动拉取权限。
 - **Props**:
   - `config?: AuthSdkConfig`
+    - `enable?: boolean` 是否启用权限 SDK，默认 false
     - `permissionApi?: PermissionApiConfig` 拉取权限接口配置
       - `timeout?: number`，默认 5000ms
       - `headers?: Record<string,string>` 自定义请求头
-    - `enable?: boolean` 是否启用权限 SDK，默认 false
     - `onError?: (error: Error) => void`
     - `onSuccess?: (data: PermissionApiResponse) => void`
   - `children: React.ReactNode`
@@ -72,6 +73,7 @@ function Home() {
 ```
 
 ### useAuth
+
 - **作用**: 访问权限状态与方法。
 - **返回**:
   - `ability: Ability` CASL `Ability` 实例
@@ -84,6 +86,7 @@ const { ability, isLoading, error, fetchPermissions } = useAuth();
 ```
 
 ### useAuthAbility
+
 - **作用**: 获取 CASL `Ability` 实例，使用 `ability.can(action, subject)` 做任意判断。
 
 ```tsx
@@ -91,8 +94,9 @@ const ability = useAuthAbility();
 const canCreate = ability.can('Editor', '@role');
 ```
 
-### Can 组件（来自 @casl/react 的 Contextual Can）
-- **作用**: 条件渲染，只有当 `I` 对 `a` 可操作时才渲染子内容；也支持 render prop。
+### Can 组件
+
+- **作用**: 条件渲染，只有当 `I` 对 `a` 可操作时才渲染子内容。 `a` 为资源类型，需要保证为 `@role`。
 
 ```tsx
 <Can I="Editor" a="@role">
@@ -101,6 +105,7 @@ const canCreate = ability.can('Editor', '@role');
 ```
 
 ### PermissionClient
+
 - **作用**: 独立的权限数据获取客户端，供非 React 场景（或自定义状态管理）使用。
 - **方法**:
   - `constructor(config?: PermissionApiConfig)`
@@ -116,6 +121,7 @@ const data = await client.fetchPermissions('user-123');
 ```
 
 ### 能力工厂（与 CASL 交互）
+
 - `createAbility({ permissions?: Permission[], roles?: string[] }): Ability`
 - `updateAbility(ability: Ability, { permissions?: Permission[], roles?: string[] }): void`
 - `convertPermissionsToRules(permissions: Permission[], roles: string[]): CaslRule[]`
@@ -133,13 +139,19 @@ updateAbility(ability, { permissions: [{ id: 'p1', name: 'Task Read', sub: 'Task
 ---
 
 ## 类型与再导出
+
 - 从本包导出的类型：`PermissionApiResponse`、`PermissionApiConfig`、`AuthSdkConfig`、`CaslRule`。
 - 便捷再导出：`MongoAbility`, `AbilityBuilder`, `AbilityClass`（来自 `@casl/ability`）。
+- 最终用户代码中仅需要使用到的 API 有：
+  - `useAuthAbility`: 获取 CASL `Ability` 实例，用于权限判断。
+  - `Can` 组件: 条件渲染，只有当 `I` 对 `a` 可操作时才渲染子内容。 `a` 为资源类型，需要保证为 `@role`。
+  - `ROLE_SUBJECT`: 特殊 subject `@role`，用于角色判断。
+  - `useAuth`: 获取权限接口的状态，配合 `fetchPermissions` 手动拉取权限数据。
 
----
 
 ## 集成建议与最佳实践
-- **权限接口返回**：`{ role_ids: string[] }`。
+
+- **直接使用组件**：`Can` 组件是直接使用的主要入口，可以使用 `useAuthAbility` 在特殊场景下手动判断权限。
 - **错误处理**：实现 `onError` 上报或提示；`onSuccess` 可做埋点。
 - **渲染时机**：根据 `useAuth()` 的 `isLoading`/`error` 渲染 Loading/Error 页，避免闪烁。
 - **与路由结合**：页面级的访问控制需要结合路由库（如 `react-router-dom`）和 `useAuthAbility` hook 来自行实现。
@@ -149,6 +161,7 @@ updateAbility(ability, { permissions: [{ id: 'p1', name: 'Task Read', sub: 'Task
 ## 进阶示例
 
 ### 菜单按权限过滤
+
 ```tsx
 import { useAuthAbility } from '@lark-apaas/auth-sdk';
 
@@ -173,10 +186,12 @@ function Nav() {
 ---
 
 ## 常见问题（FAQ）
+
 - **如何做角色判断？** 角色被映射为对特殊 subject `@role` 的 action。你可以使用 `ability.can('admin_role', '@role')` 来判断当前用户是否拥有 `admin_role` 角色。
-- **如何实现路由守卫？** 由于 `CanRoute` 组件已移除，您需要结合您使用的路由库（如 `react-router-dom`）和 `useAuthAbility` hook 来手动实现路由守卫。通过在路由渲染前检查权限，然后决定是否渲染组件或重定向。
+- **如何实现路由守卫？** 您需要结合您使用的路由库（如 `react-router-dom`）和 `useAuthAbility` hook 来手动实现路由守卫。通过在路由渲染前检查权限，然后决定是否渲染组件或重定向。
 
 ---
 
 ## 许可
+
 MIT

package/lib/index.d.ts

@@ -4,10 +4,9 @@
  * 基于 CASL 的前端鉴权 SDK
  * 封装了权限数据获取和 Ability 初始化逻辑
  */
-export type { Action, Subject, Permission, UserRole, PermissionApiResponse, PermissionApiConfig, AuthSdkConfig, CaslRule, } from './types';
-export { createAbility, updateAbility, convertPermissionsToRules, ROLE_SUBJECT, } from './ability-factory';
+export type { PermissionApiResponse, PermissionApiConfig, AuthSdkConfig, } from './types';
+export { ROLE_SUBJECT } from './ability-factory';
 export { PermissionClient } from './permission-client';
 export { AuthProvider, useAuth, useAuthAbility, Can, AbilityContext, } from './AuthProvider';
 export type { AuthProviderProps } from './AuthProvider';
-export { MongoAbility, AbilityBuilder, type AbilityClass } from '@casl/ability';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,MAAM,EACN,OAAO,EACP,UAAU,EACV,QAAQ,EACR,qBAAqB,EACrB,mBAAmB,EACnB,aAAa,EACb,QAAQ,GACT,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,aAAa,EACb,aAAa,EACb,yBAAyB,EACzB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EACL,YAAY,EACZ,OAAO,EACP,cAAc,EACd,GAAG,EACH,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,aAAa,GACd,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EACL,YAAY,EACZ,OAAO,EACP,cAAc,EACd,GAAG,EACH,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/lib/index.js

@@ -1,5 +1,4 @@
-import { ROLE_SUBJECT, convertPermissionsToRules, createAbility, updateAbility } from "./ability-factory.js";
+import { ROLE_SUBJECT } from "./ability-factory.js";
 import { PermissionClient } from "./permission-client.js";
 import { AbilityContext, AuthProvider, Can, useAuth, useAuthAbility } from "./AuthProvider.js";
-import { AbilityBuilder, MongoAbility } from "@casl/ability";
-export { AbilityBuilder, AbilityContext, AuthProvider, Can, MongoAbility, PermissionClient, ROLE_SUBJECT, convertPermissionsToRules, createAbility, updateAbility, useAuth, useAuthAbility };
+export { AbilityContext, AuthProvider, Can, PermissionClient, ROLE_SUBJECT, useAuth, useAuthAbility };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/auth-sdk",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "description": "基于 CASL 的前端鉴权 SDK",
   "types": "./lib/index.d.ts",
   "main": "./lib/index.js",