@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");

// Functional permission and data scope are separate. For model data,
// append rowFilter to the JSONQL query before reading or mutating rows.
// `scope === "none"` is represented by an always-false rowFilter.
const runtimeRowConstraint = result.rowFilter?.filter;

// 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

API Overview

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

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

if (!allow) throw new Error("Forbidden");
// `own`, `dep`, `dep_and_sub`, `mixed`, and `none` all require the business
// data path to consume rowFilter. `none` contains an always-false condition.
const runtimeRowConstraint = rowFilter?.filter;

// 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

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

// 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

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

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

// 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

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:

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

Prebind an existing user to WeCom

await admin.auth.bindUserOAuth(userUid, {
  provider: "wecom",
  providerUserId: "enterprise-member-userid",
});

Server-only: calls POST /api/internal/auth/users/{uid}/oauth-bindings with the environment-scoped Service Key. Edge Functions must authenticate their caller and authorize user management before calling it. Use a stable application UID, not a numeric database ID. Identical bindings are idempotent; conflicts return 409 and never move an identity. Missing/disabled users return 404. Only WeCom is supported. Use verified member IDs from the intended enterprise; this operation does not fetch WeCom contact information or prove membership. Deploy the matching Runtime endpoint before using the method.