@amaster.ai/admin-sdk

Server-side Admin SDK for the Amaster platform. Manages users, roles, permissions, and departments via the internal API. Designed for Edge Functions (Deno) and Node.js backends — uses native fetch, no browser APIs.

Edge Function 快速示例（AI 参考）

在 AMaster edge-function 中，从 env 获取参数初始化 SDK：

import { AdminSDK } from "npm:@amaster.ai/admin-sdk";

export default async function (request: Request, env: Env): Promise<Response> {
  const admin = new AdminSDK({
    appId: env.appId,
    env: env.appEnv,
    serviceKey: env.vars["APP_SECRET"],
  });

  // 权限校验
  const { allow } = await admin.auth.checkPermission("user-uid", {
    resource: "page",
    action: "access",
  });
  if (!allow) return Response.json({ error: "Forbidden" }, { status: 403 });

  // 创建用户
  const user = await admin.users.create({
    email: "[email protected]",
    password: "Secure@123",
    displayName: "New User",
  });

  return Response.json({ user });
}

参数映射：env.appId → appId，env.appEnv → env，env.vars["APP_SECRET"] → serviceKey。baseURL 有默认值，可不传。

Installation

pnpm add @amaster.ai/admin-sdk
# or
npm install @amaster.ai/admin-sdk

Quick Start

import { AdminSDK } from "@amaster.ai/admin-sdk";

const admin = new AdminSDK({
  baseURL: process.env.RUNTIME_URL || "http://localhost:3000",
  appId: process.env.APP_ID!,
  env: process.env.ENV || "dev",
  serviceKey: process.env.SERVICE_KEY, // Required for internal API calls
});

// Check if a user can access a resource
const result = await admin.auth.checkPermission("user-uid-here", {
  resource: "page",
  action: "access",
  resourceId: "dashboard",
});
if (!result.allow) throw new Error("Forbidden");

// Create a user
const user = await admin.users.create({
  email: "[email protected]",
  password: "Secure@123",
  displayName: "New User",
});

// Assign a role to the user (use uid, not numeric id)
await admin.roles.assign(roleId, {
  assigneeType: "user",
  assigneeUid: user.uid,
});

Environment Variables

| Variable | Description | Example | |----------------|--------------------------------------|----------------------------| | RUNTIME_URL | Runtime service base URL | http://runtime:3000 | | APP_ID | Application ID (x-tenant-id) | d9990247 | | ENV | Environment (x-env) | dev | prod | | SERVICE_KEY | Service key for internal API auth | (from Amaster console) |

API Overview

admin.auth — Permission checks (no user token required)

| Method | Description | |-------------------|--------------------------------------------------| | checkPermission(uid, { resource, action, resourceId? }) | Check if user has permission | | getRules(uid) | Get full ACL rules (roles + permissions) for a user |

// Single permission check
const { allow, roles, permissions } = await admin.auth.checkPermission(uid, {
  resource: "order",
  action: "read",
  resourceId: "123", // Optional, for scope validation
});

// Batch: fetch rules once, check locally
const rules = await admin.auth.getRules(uid);
const canExport = rules.permissions.some(
  (p) => p.resource === "report" && p.action === "export"
);

admin.users — User CRUD

| Method | Description | |---------------------|--------------------------------| | list(params?) | List users (pagination, search)| | get(uid) | Get user by UID | | create(params) | Create user | | update(uid, params) | Update user | | delete(uid) | Delete user |

const { list, total } = await admin.users.list({ query: "zhang", pageSize: 20 });
const user = await admin.users.get("abc-uid");
await admin.users.update(user.uid, { displayName: "New Name" });

admin.roles — Role management

| Method | Description | |---------------------------|--------------------------------------| | list() | List all roles | | get(id) | Get role by ID | | create(params) | Create role | | update(id, params) | Update role | | delete(id) | Delete role (non-system only) | | assign(roleId, params) | Assign role to user/dept/team | | unassign(roleId, params)| Remove assignment | | listAssignees(roleId) | List assignees of a role | | getUserRoles(uid) | Get roles assigned to a user |

// Prefer assigneeUid for users
await admin.roles.assign(roleId, {
  assigneeType: "user",
  assigneeUid: user.uid,
});

// For department/team/role, use assigneeId
await admin.roles.assign(roleId, {
  assigneeType: "department",
  assigneeId: 5,
});

const roles = await admin.roles.getUserRoles(user.uid);

admin.permissions — Permission definitions and assignments

| Method | Description | |-------------------------------------|--------------------------------------| | list() | List all permissions | | create(params) | Create permission | | update(id, params) | Update permission | | delete(id) | Delete permission | | listForRole(roleId) | List permissions for a role | | assignToRole(roleId, params) | Assign permission to role | | removeFromRole(roleId, permId) | Remove permission from role | | updateRolePermissionScope(...) | Update role-permission scope | | assignToUser(uid, params) | Direct user permission (exception) | | removeFromUser(uid, permId) | Remove user permission | | listForUser(uid) | List user permission exceptions | | updateUserPermissionScope(...) | Update user permission scope |

const perm = await admin.permissions.create({
  resource: "order",
  action: "export",
  name: "导出订单",
});

await admin.permissions.assignToRole(roleId, {
  permissionId: perm.id,
  scopeType: "department",
});

// User-level override (bypasses role)
await admin.permissions.assignToUser(uid, {
  permissionId: perm.id,
  scopeType: "custom",
  scopeFilter: JSON.stringify({ id: [1, 2, 3] }),
});

admin.departments — Department and membership

| Method | Description | |---------------------------|--------------------------------------| | list() | List all departments | | get(id) | Get department by ID | | create(params) | Create department | | update(id, params) | Update department | | delete(id) | Delete department | | listUsers(id, includeChildren?) | List department members | | addUser(deptId, params) | Add user to department (use userUid) | | removeUser(deptId, userUid) | Remove user from department |

const dept = await admin.departments.create({ name: "技术部", parentId: 1 });
await admin.departments.addUser(dept.id, {
  userUid: user.uid,
  position: "工程师",
  isPrimary: true,
});
await admin.departments.removeUser(dept.id, user.uid);

Deno / Edge Functions

在 edge-function 中通过 npm: 导入，参数从 env 获取（见顶部「Edge Function 快速示例」）。

Identifiers: UID vs numeric ID

• UID (string, e.g. "abc-123-def"): Primary user identifier. Use for users.get/update/delete, roles.assign (assigneeUid), departments.addUser/removeUser, auth.checkPermission, permissions.assignToUser.
• Numeric ID (number): Database ID. Used for roles, permissions, departments, and role-assignee lookups. Prefer UID when the API supports it.

Types (AI Reference)

All types are exported from the package. Key ones:

| Type | Use case | |------|----------| | AdminSDKOptions | Constructor options | | CheckPermissionParams, CheckPermissionResult | auth.checkPermission | | CreateUserParams, CreateUserResult, UserDetail | User CRUD | | RoleAssignParams, Role | Role assignment (use assigneeUid for users) | | AssignPermissionToRoleParams, AssignPermissionToUserParams | Permission assignment | | AddDepartmentMemberParams | Department membership (use userUid) |

import type { AdminSDKOptions, CreateUserParams, RoleAssignParams } from "@amaster.ai/admin-sdk";

Error Handling

import { AdminSDK, AdminSDKError } from "@amaster.ai/admin-sdk";

try {
  await admin.users.get("invalid-uid");
} catch (err) {
  if (err instanceof AdminSDKError) {
    console.error(err.status, err.message); // 404, "user not found"
  }
}

License

MIT