@amaster.ai/admin-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,719 @@
+interface RequestOptions {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}
+type RequestFn = <T>(options: RequestOptions) => Promise<T>;
+
+interface AdminSDKOptions {
+    /** Runtime service base URL, e.g. http://runtime:3000 */
+    baseURL: string;
+    /** Application ID, sent as x-tenant-id header */
+    appId: string;
+    /** Environment identifier, sent as x-env header. Defaults to "dev" */
+    env?: string;
+    /** Service key for bypassing user-level auth checks */
+    serviceKey?: string;
+}
+interface CheckPermissionParams {
+    /** Resource type, e.g. "page", "order", "report" */
+    resource: string;
+    /** Action type, e.g. "access", "read", "write", "delete" */
+    action: string;
+    /**
+     * Specific resource key/ID for fine-grained data scope validation.
+     * Required when the role's scopeType is "own", "dep", or "custom".
+     *
+     * - all: not needed
+     * - own: owner uid of the resource
+     * - dep: department id of the resource
+     * - custom: resource key matched against the role's scopeFilter whitelist
+     */
+    resourceId?: string;
+}
+interface CheckPermissionResult {
+    allow: boolean;
+    reason: string;
+    scope: "all" | "dep" | "own" | "custom" | null;
+    resourceId: string | null;
+    roles: string[];
+    permissions: Array<{
+        resource: string;
+        action: string;
+        scopeType: string;
+    }>;
+}
+interface AclRules {
+    appId: string;
+    env: string;
+    user: {
+        uid: string;
+        username: string | null;
+    };
+    permissions: Array<{
+        resource: string;
+        action: string;
+        scopeType: "all" | "dep" | "own" | "custom";
+        scopeFilter?: string;
+    }>;
+    roles: string[];
+}
+interface UserListItem {
+    /** Numeric database ID, used for role/department assignment */
+    id: number;
+    uid: string;
+    username: string | null;
+    email: string | null;
+    phone: string | null;
+    displayName: string | null;
+    avatarUrl: string | null;
+    createdAt: string;
+}
+interface UserDetail extends UserListItem {
+    updatedAt: string;
+}
+interface UserListResult {
+    list: UserListItem[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+interface UserListParams {
+    page?: number;
+    pageSize?: number;
+    /** Search by username, email, phone, or displayName */
+    query?: string;
+}
+interface CreateUserParams {
+    username?: string;
+    email?: string;
+    phone?: string;
+    /** Minimum 8 characters */
+    password: string;
+    displayName?: string;
+}
+interface CreateUserResult {
+    /** Numeric database ID, used for role/department assignment */
+    id: number;
+    uid: string;
+    username: string | null;
+    email: string | null;
+    displayName: string | null;
+    createdAt: string;
+}
+interface UpdateUserParams {
+    username?: string;
+    displayName?: string;
+    email?: string;
+    phone?: string;
+    avatarUrl?: string;
+    /** Reset password */
+    password?: string;
+    isSuperAdmin?: boolean;
+}
+interface UpdateUserResult {
+    uid: string;
+    displayName: string | null;
+    updatedAt: string;
+}
+interface Role {
+    id: number;
+    code: string;
+    displayName: string;
+    description: string;
+    isSystem: boolean;
+    createdAt: string;
+}
+interface CreateRoleParams {
+    code: string;
+    displayName?: string;
+    description?: string;
+}
+interface UpdateRoleParams {
+    code?: string;
+    displayName?: string;
+    description?: string;
+}
+type AssigneeType = "user" | "team" | "department" | "role";
+interface RoleAssignParams {
+    assigneeType: AssigneeType;
+    /** Use assigneeUid for user type (preferred). assigneeId for department/role/team. */
+    assigneeUid?: string;
+    assigneeId?: number;
+}
+interface RoleAssignee {
+    id: number;
+    roleId: number;
+    assigneeType: AssigneeType;
+    assigneeId: number;
+    createdAt: string;
+    user?: {
+        id: number;
+        username: string | null;
+        displayName: string | null;
+        email: string | null;
+    };
+    department?: {
+        id: number;
+        name: string;
+        parentId: number | null;
+    };
+    assigneeRole?: {
+        id: number;
+        code: string;
+        displayName: string;
+    };
+}
+interface Permission {
+    id: number;
+    name: string;
+    resource: string;
+    action: string;
+    description: string;
+    sourceType: string;
+    createdAt: string;
+}
+interface CreatePermissionParams {
+    resource: string;
+    action: string;
+    name?: string;
+    description?: string;
+}
+interface UpdatePermissionParams {
+    resource?: string;
+    action?: string;
+    name?: string;
+    description?: string;
+}
+type ScopeType = "all" | "self" | "department" | "custom";
+interface RolePermission {
+    id: number;
+    roleId: number;
+    permissionId: number;
+    scopeType: ScopeType;
+    scopeFilter?: string;
+    permission: {
+        resource: string;
+        action: string;
+    };
+}
+interface AssignPermissionToRoleParams {
+    permissionId: number;
+    /** Data scope type. Defaults to "all" */
+    scopeType?: ScopeType;
+    /** Custom filter condition (JSON string), used when scopeType is "custom" */
+    scopeFilter?: string;
+}
+interface UpdatePermissionScopeParams {
+    scopeType: ScopeType;
+    scopeFilter?: string;
+}
+interface AssignPermissionToUserParams {
+    permissionId: number;
+    /** Data scope type. Defaults to "all" */
+    scopeType?: ScopeType;
+    /** Custom filter condition (JSON string), used when scopeType is "custom" */
+    scopeFilter?: string;
+}
+interface UserPermissionException {
+    id: number;
+    userId: number;
+    permissionId: number;
+    scopeType: ScopeType;
+    scopeFilter?: string;
+    permission: {
+        resource: string;
+        action: string;
+    };
+}
+interface Department {
+    id: number;
+    code: string;
+    name: string;
+    parentId: number | null;
+    path: string | null;
+    level: number;
+    managerId: number | null;
+    createdAt: string;
+}
+interface CreateDepartmentParams {
+    name: string;
+    parentId?: number;
+    /** Department manager's numeric user ID */
+    managerId?: number;
+}
+interface UpdateDepartmentParams {
+    name?: string;
+    parentId?: number;
+    managerId?: number;
+}
+interface DepartmentMember {
+    id: number;
+    userId: number;
+    departmentId: number;
+    isPrimary: boolean;
+    position: string | null;
+    user: {
+        id: number;
+        username: string | null;
+        displayName: string | null;
+    };
+}
+interface AddDepartmentMemberParams {
+    /** User UID (UUID string) */
+    userUid: string;
+    position?: string;
+    isPrimary?: boolean;
+}
+
+declare function createAuthModule(request: RequestFn): {
+    /**
+     * Check whether a user has a specific permission.
+     *
+     * Uses the Service Key to query on behalf of any user by UID —
+     * no user token required.
+     *
+     * @example
+     * ```typescript
+     * // Check if user can access the dashboard page
+     * const result = await admin.auth.checkPermission('u-123456', {
+     *   resource: 'page',
+     *   action: 'access',
+     *   resourceId: 'dashboard',
+     * });
+     * if (!result.allow) throw new Error('Forbidden');
+     * ```
+     */
+    checkPermission(uid: string, params: CheckPermissionParams): Promise<CheckPermissionResult>;
+    /**
+     * Get all ACL rules for a user.
+     *
+     * Returns the full set of permissions and roles. Useful when you need
+     * to perform multiple permission checks locally without making repeated
+     * network calls.
+     *
+     * @example
+     * ```typescript
+     * const rules = await admin.auth.getRules('u-123456');
+     *
+     * // Check roles
+     * if (rules.roles.includes('admin')) { ... }
+     *
+     * // Check multiple permissions locally
+     * const canRead = rules.permissions.some(
+     *   p => p.resource === 'order' && p.action === 'read'
+     * );
+     * ```
+     */
+    getRules(uid: string): Promise<AclRules>;
+};
+
+declare function createDepartmentsModule(request: RequestFn): {
+    /**
+     * List all departments (flat list).
+     *
+     * @example
+     * ```typescript
+     * const depts = await admin.departments.list();
+     * const techDept = depts.find(d => d.name === '技术部');
+     * ```
+     */
+    list(): Promise<Department[]>;
+    /**
+     * Get a single department by ID.
+     *
+     * @example
+     * ```typescript
+     * const dept = await admin.departments.get(1);
+     * ```
+     */
+    get(id: number): Promise<Department>;
+    /**
+     * Create a new department.
+     *
+     * @example
+     * ```typescript
+     * const dept = await admin.departments.create({
+     *   name: '测试组',
+     *   parentId: 1,
+     * });
+     * ```
+     */
+    create(params: CreateDepartmentParams): Promise<Department>;
+    /**
+     * Update a department.
+     *
+     * @example
+     * ```typescript
+     * await admin.departments.update(3, { name: '质量保证组' });
+     * ```
+     */
+    update(id: number, params: UpdateDepartmentParams): Promise<void>;
+    /**
+     * Delete a department.
+     * Note: departments with sub-departments or assigned users cannot be deleted directly.
+     *
+     * @example
+     * ```typescript
+     * await admin.departments.delete(3);
+     * ```
+     */
+    delete(id: number): Promise<void>;
+    /**
+     * List members of a department.
+     *
+     * @param includeChildren - Whether to include members from sub-departments. Defaults to false.
+     *
+     * @example
+     * ```typescript
+     * const members = await admin.departments.listUsers(1);
+     * const allMembers = await admin.departments.listUsers(1, true);
+     * ```
+     */
+    listUsers(id: number, includeChildren?: boolean): Promise<DepartmentMember[]>;
+    /**
+     * Add a user to a department.
+     *
+     * @example
+     * ```typescript
+     * await admin.departments.addUser(1, {
+     *   userId: 123,
+     *   isPrimary: true,
+     *   position: '高级工程师',
+     * });
+     * ```
+     */
+    addUser(deptId: number, params: AddDepartmentMemberParams): Promise<void>;
+    /**
+     * Remove a user from a department.
+     *
+     * @example
+     * ```typescript
+     * await admin.departments.removeUser(1, 123);
+     * ```
+     */
+    removeUser(deptId: number, userUid: string): Promise<void>;
+};
+
+declare function createPermissionsModule(request: RequestFn): {
+    /**
+     * List all defined permissions.
+     *
+     * @example
+     * ```typescript
+     * const perms = await admin.permissions.list();
+     * const orderRead = perms.find(p => p.resource === 'order' && p.action === 'read');
+     * ```
+     */
+    list(): Promise<Permission[]>;
+    /**
+     * Create a new permission definition.
+     *
+     * @example
+     * ```typescript
+     * const perm = await admin.permissions.create({
+     *   resource: 'order',
+     *   action: 'export',
+     *   name: '导出订单',
+     * });
+     * ```
+     */
+    create(params: CreatePermissionParams): Promise<Permission>;
+    /**
+     * Update a permission definition.
+     *
+     * @example
+     * ```typescript
+     * await admin.permissions.update(10, { name: '导出报表' });
+     * ```
+     */
+    update(id: number, params: UpdatePermissionParams): Promise<void>;
+    /**
+     * Delete a permission definition.
+     *
+     * @example
+     * ```typescript
+     * await admin.permissions.delete(10);
+     * ```
+     */
+    delete(id: number): Promise<void>;
+    /**
+     * List all permissions assigned to a role.
+     *
+     * @example
+     * ```typescript
+     * const perms = await admin.permissions.listForRole(roleId);
+     * ```
+     */
+    listForRole(roleId: number): Promise<RolePermission[]>;
+    /**
+     * Assign a permission to a role with a data scope.
+     *
+     * @example
+     * ```typescript
+     * // Department-scoped permission
+     * await admin.permissions.assignToRole(roleId, {
+     *   permissionId: 10,
+     *   scopeType: 'department',
+     * });
+     *
+     * // Custom whitelist scope
+     * await admin.permissions.assignToRole(roleId, {
+     *   permissionId: 20,
+     *   scopeType: 'custom',
+     *   scopeFilter: JSON.stringify({ id: [1, 2, 3] }),
+     * });
+     * ```
+     */
+    assignToRole(roleId: number, params: AssignPermissionToRoleParams): Promise<void>;
+    /**
+     * Remove a permission from a role.
+     *
+     * @example
+     * ```typescript
+     * await admin.permissions.removeFromRole(roleId, permId);
+     * ```
+     */
+    removeFromRole(roleId: number, permId: number): Promise<void>;
+    /**
+     * Update the data scope of a role–permission assignment.
+     *
+     * @example
+     * ```typescript
+     * await admin.permissions.updateRolePermissionScope(roleId, permId, {
+     *   scopeType: 'all',
+     * });
+     * ```
+     */
+    updateRolePermissionScope(roleId: number, permId: number, params: UpdatePermissionScopeParams): Promise<void>;
+    /**
+     * Assign a direct (user-level) permission exception to a user.
+     *
+     * This bypasses role-based assignment and gives the user a direct
+     * data-scope override for the specified permission.
+     *
+     * @example
+     * ```typescript
+     * await admin.permissions.assignToUser('u-123456', {
+     *   permissionId: 10,
+     *   scopeType: 'department',
+     * });
+     * ```
+     */
+    assignToUser(uid: string, params: AssignPermissionToUserParams): Promise<void>;
+    /**
+     * Remove a direct permission exception from a user.
+     *
+     * @example
+     * ```typescript
+     * await admin.permissions.removeFromUser('u-123456', permId);
+     * ```
+     */
+    removeFromUser(uid: string, permId: number): Promise<void>;
+    /**
+     * List permission exceptions for a specific user.
+     *
+     * @example
+     * ```typescript
+     * const exceptions = await admin.permissions.listForUser('u-123456');
+     * ```
+     */
+    listForUser(uid: string): Promise<UserPermissionException[]>;
+    /**
+     * Update the data scope of a user-level permission exception.
+     *
+     * @example
+     * ```typescript
+     * await admin.permissions.updateUserPermissionScope('u-123456', permId, {
+     *   scopeType: 'custom',
+     *   scopeFilter: JSON.stringify({ id: [10, 20] }),
+     * });
+     * ```
+     */
+    updateUserPermissionScope(uid: string, permId: number, params: UpdatePermissionScopeParams): Promise<void>;
+};
+
+declare function createRolesModule(request: RequestFn): {
+    /**
+     * List all roles.
+     *
+     * @example
+     * ```typescript
+     * const roles = await admin.roles.list();
+     * const managerRole = roles.find(r => r.code === 'manager');
+     * ```
+     */
+    list(): Promise<Role[]>;
+    /**
+     * Get a role by its numeric ID.
+     *
+     * @example
+     * ```typescript
+     * const role = await admin.roles.get(1);
+     * ```
+     */
+    get(id: number): Promise<Role>;
+    /**
+     * Create a new role.
+     *
+     * @example
+     * ```typescript
+     * const role = await admin.roles.create({
+     *   code: 'editor',
+     *   displayName: '编辑',
+     *   description: '负责内容编辑',
+     * });
+     * ```
+     */
+    create(params: CreateRoleParams): Promise<Role>;
+    /**
+     * Update a role.
+     * Note: system roles (isSystem=true) cannot be modified.
+     *
+     * @example
+     * ```typescript
+     * await admin.roles.update(3, { displayName: '高级编辑' });
+     * ```
+     */
+    update(id: number, params: UpdateRoleParams): Promise<void>;
+    /**
+     * Delete a role.
+     * Note: system roles cannot be deleted.
+     *
+     * @example
+     * ```typescript
+     * await admin.roles.delete(3);
+     * ```
+     */
+    delete(id: number): Promise<void>;
+    /**
+     * Assign a role to a user, department, team, or another role.
+     *
+     * @example
+     * ```typescript
+     * // Assign to a user
+     * await admin.roles.assign(roleId, { assigneeType: 'user', assigneeId: 123 });
+     *
+     * // Assign to an entire department
+     * await admin.roles.assign(roleId, { assigneeType: 'department', assigneeId: 5 });
+     * ```
+     */
+    assign(roleId: number, params: RoleAssignParams): Promise<void>;
+    /**
+     * Remove a role assignment.
+     *
+     * @example
+     * ```typescript
+     * await admin.roles.unassign(roleId, { assigneeType: 'user', assigneeId: 123 });
+     * ```
+     */
+    unassign(roleId: number, params: RoleAssignParams): Promise<void>;
+    /**
+     * List all assignees (users, departments, etc.) for a role.
+     *
+     * @example
+     * ```typescript
+     * const assignees = await admin.roles.listAssignees(roleId);
+     * const users = assignees.filter(a => a.assigneeType === 'user');
+     * ```
+     */
+    listAssignees(roleId: number): Promise<RoleAssignee[]>;
+    /**
+     * Get all roles assigned to a user (by UID).
+     *
+     * Useful in Edge Functions to check what roles a user currently holds
+     * without making a full ACL check.
+     *
+     * @example
+     * ```typescript
+     * const roles = await admin.roles.getUserRoles('u-123456');
+     * if (roles.some(r => r.code === 'admin')) { ... }
+     * ```
+     */
+    getUserRoles(uid: string): Promise<Role[]>;
+};
+
+declare function createUsersModule(request: RequestFn): {
+    /**
+     * List users with optional search and pagination.
+     *
+     * @example
+     * ```typescript
+     * const result = await admin.users.list({ query: 'zhang', pageSize: 50 });
+     * console.log(`Total: ${result.total}`);
+     * for (const user of result.list) {
+     *   console.log(user.email);
+     * }
+     * ```
+     */
+    list(params?: UserListParams): Promise<UserListResult>;
+    /**
+     * Get a single user by UID.
+     *
+     * @example
+     * ```typescript
+     * const user = await admin.users.get('u-123456');
+     * console.log(user.email);
+     * ```
+     */
+    get(uid: string): Promise<UserDetail>;
+    /**
+     * Create a new user.
+     * At least one of username / email / phone must be provided.
+     *
+     * @example
+     * ```typescript
+     * const user = await admin.users.create({
+     *   email: 'user@example.com',
+     *   password: 'Secure@123',
+     *   displayName: '张三',
+     * });
+     * ```
+     */
+    create(params: CreateUserParams): Promise<CreateUserResult>;
+    /**
+     * Update an existing user.
+     *
+     * @example
+     * ```typescript
+     * // Reset password
+     * await admin.users.update('u-123456', { password: 'NewSecure@456' });
+     *
+     * // Grant super admin
+     * await admin.users.update('u-123456', { isSuperAdmin: true });
+     * ```
+     */
+    update(uid: string, params: UpdateUserParams): Promise<UpdateUserResult>;
+    /**
+     * Delete a user.
+     *
+     * @example
+     * ```typescript
+     * await admin.users.delete('u-123456');
+     * ```
+     */
+    delete(uid: string): Promise<void>;
+};
+
+declare class AdminSDK {
+    /** Check and query user permissions without requiring a user token */
+    readonly auth: ReturnType<typeof createAuthModule>;
+    /** User CRUD operations */
+    readonly users: ReturnType<typeof createUsersModule>;
+    /** Role management and assignment */
+    readonly roles: ReturnType<typeof createRolesModule>;
+    /** Permission definitions and role/user permission scopes */
+    readonly permissions: ReturnType<typeof createPermissionsModule>;
+    /** Department management and membership */
+    readonly departments: ReturnType<typeof createDepartmentsModule>;
+    constructor(options: AdminSDKOptions);
+}
+
+declare class AdminSDKError extends Error {
+    readonly statusCode: number;
+    readonly response?: unknown | undefined;
+    constructor(message: string, statusCode: number, response?: unknown | undefined);
+}
+
+export { type AclRules, type AddDepartmentMemberParams, AdminSDK, AdminSDKError, type AdminSDKOptions, type AssignPermissionToRoleParams, type AssigneeType, type CheckPermissionParams, type CheckPermissionResult, type CreateDepartmentParams, type CreatePermissionParams, type CreateRoleParams, type CreateUserParams, type CreateUserResult, type Department, type DepartmentMember, type Permission, type Role, type RoleAssignParams, type RoleAssignee, type RolePermission, type ScopeType, type UpdateDepartmentParams, type UpdatePermissionParams, type UpdatePermissionScopeParams, type UpdateRoleParams, type UpdateUserParams, type UpdateUserResult, type UserDetail, type UserListItem, type UserListParams, type UserListResult, type UserPermissionException };