@amaster.ai/admin-sdk 1.1.72 → 1.1.73

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,18 +1,21 @@
1
1
  # @amaster.ai/admin-sdk
2
2
 
3
- 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.
3
+ Application domains determine application and environment. See [functionality and compatibility](../../docs/app-tenancy-implementation.md) for API scope and validation status.
4
+
5
+ Server-side Admin SDK for the Amaster platform. Manages users, roles, permissions, and departments through Runtime administration APIs. Designed for **Edge Functions** (Deno) and Node.js backends — uses native `fetch`, no browser APIs.
4
6
 
5
7
  ## Edge Function 快速示例(AI 参考)
6
8
 
7
- 在 AMaster edge-function 中,从 `env` 获取参数初始化 SDK:
9
+ 使用应用域名初始化 SDK,应用和环境由后端识别;管理凭据从函数环境读取:
8
10
 
9
11
  ```typescript
10
12
  import { AdminSDK } from "npm:@amaster.ai/admin-sdk";
11
13
 
12
14
  export default async function (request: Request, env: Env): Promise<Response> {
15
+ const appURL = env.vars.APP_URL;
16
+ const baseURL = /^https?:\/\//i.test(appURL) ? appURL : `https://${appURL}`;
13
17
  const admin = new AdminSDK({
14
- appId: env.appId,
15
- env: env.appEnv,
18
+ baseURL,
16
19
  serviceKey: env.vars["APP_SECRET"],
17
20
  });
18
21
 
@@ -34,7 +37,52 @@ export default async function (request: Request, env: Env): Promise<Response> {
34
37
  }
35
38
  ```
36
39
 
37
- **参数映射**:`env.appId` → appId,`env.appEnv` → env,`env.vars["APP_SECRET"]` → serviceKey。baseURL 有默认值,可不传。
40
+ `APP_URL` 由平台按当前应用环境自动注入,无需用户新增配置;只有域名时补齐协议,已有协议则保持原值。`env.vars["APP_SECRET"]` 是原有服务端管理凭据,不需要人类访问令牌。不要将该凭据提供给业务浏览器。
41
+
42
+ ## Tenant administration
43
+
44
+ The original `APP_SECRET` represents the application's backend administrator. Existing `admin.auth/users/roles/permissions/departments` calls keep their default-tenant behavior. Explicitly select a target tenant to use those management modules or read and write its business data:
45
+
46
+ ```typescript
47
+ const admin = new AdminSDK({ baseURL, serviceKey: env.vars.APP_SECRET });
48
+ const tenant = admin.tenancy.forTenant(tenantId);
49
+ const order = await tenant.entity.get("default", "orders", orderId);
50
+ ```
51
+
52
+ No human token or separate service account is required for this backend path. The backend verifies the application's key and target tenant and audits a service actor. App Admin pages instead retain the platform application's management session and a verified account link for the actual human; they do not need membership in each tenant. Upstream business projection fields remain read-only. Ordinary business calls retain their original caller permissions.
53
+
54
+ All AdminSDK administration uses the application service key, including revision-based tenant member and authorization methods. There is no human-token overload. Current-user business functions use `env.rbac` and `env.tenancy`; the platform binds their verified execution identity and tenant.
55
+
56
+ ```typescript
57
+ const management = admin.tenancy.forTenant(appTenantId);
58
+ const result = await management.putMember({ expectedRevision, subject: member, active: true });
59
+ ```
60
+
61
+ The shared implementation lives in `@amaster.ai/auth-client/rbac` and `@amaster.ai/auth-client/tenant-management`. AdminSDK supplies application authority; execution hosts supply current-user authority. Original methods preserve their return values and `AdminSDKError`. Revision-based methods return `{ data, status, error }` and use the current `tenantAuthorizationRevision`.
62
+
63
+ ## Existing department and role APIs
64
+
65
+ Keep the existing `admin.departments` and `admin.roles.assign/unassign` operations. Departments, teams, positions and role assignment remain their original business concepts; tenancy only scopes their data and operations. Existing department managers and BPM people lookup must retain their behavior.
66
+
67
+ Tenant administration uses the original department and role-assignment concepts. Internal authorization graph records support migration, current permissions and BPM people lookup; they are not a second organization or inheritance management API.
68
+
69
+
70
+ ```ts
71
+ const tenantAdmin = admin.tenancy.forTenant(appTenantId);
72
+ const department = await tenantAdmin.departments.create({ name: '销售部', parentId });
73
+ await tenantAdmin.departments.addUser(department.id, { userUid, isPrimary: true });
74
+ // A 包含 B:把 B 分配给 A,沿用原角色包含方向。
75
+ await tenantAdmin.roles.assign(roleBId, { assigneeType: 'role', assigneeId: roleAId });
76
+ const permissions = await tenantAdmin.permissions.list();
77
+ ```
78
+
79
+ 上述模块沿用原返回值;失败抛出 `AdminSDKError`,不转换成 revision 接口的 `{ data, status, error }`。401/403/409 不自动重试写入。成员及角色停用等显式修订接口使用当前 `tenantAuthorizationRevision`;重新授权和角色包含复用原管理方法,不增加独立审核恢复流程。
80
+
81
+ ## Role inclusion
82
+
83
+ Role inclusion already exists: when role A includes B, users holding A gain B's permissions. Use the existing `admin.roles.assign(roleBId, { assigneeType: "role", assigneeId: roleAId })` contract for its original scope. Tenancy adds isolation of the relation; it does not require a second role feature.
84
+
85
+ Within a selected tenant, use `management.roles.assign(roleBId, { assigneeType: "role", assigneeId: roleAId })`. This uses the application key, selected tenant and service-actor audit. Existing root `admin.roles` calls keep their service-key authentication and default-tenant compatibility.
38
86
 
39
87
  ## Installation
40
88
 
@@ -49,11 +97,11 @@ npm install @amaster.ai/admin-sdk
49
97
  ```typescript
50
98
  import { AdminSDK } from "@amaster.ai/admin-sdk";
51
99
 
100
+ const appURL = process.env.APP_URL!; // Existing platform-managed application variable.
101
+ const baseURL = /^https?:\/\//i.test(appURL) ? appURL : `https://${appURL}`;
52
102
  const admin = new AdminSDK({
53
- baseURL: process.env.RUNTIME_URL || "http://localhost:3000",
54
- appId: process.env.APP_ID!,
55
- env: process.env.ENV || "dev",
56
- serviceKey: process.env.SERVICE_KEY, // Required for internal API calls
103
+ baseURL,
104
+ serviceKey: process.env.APP_SECRET, // Required for internal API calls
57
105
  });
58
106
 
59
107
  // Check if a user can access a resource
@@ -83,14 +131,11 @@ await admin.roles.assign(roleId, {
83
131
  });
84
132
  ```
85
133
 
86
- ## Environment Variables
134
+ ## Application context
135
+
136
+ Build `baseURL` from the existing platform-managed `APP_URL` for the current application environment; `appId` and `env` are not required. Before the first operation, the SDK verifies `/api/auth/context` and uses the application/environment returned by the backend. Existing `env` arguments cannot override the backend result. Discovery failures stop the operation; later calls may retry discovery. Domain discovery does not grant administrative authority.
87
137
 
88
- | Variable | Description | Example |
89
- |----------------|--------------------------------------|----------------------------|
90
- | `RUNTIME_URL` | Runtime service base URL | `http://runtime:3000` |
91
- | `APP_ID` | Application ID (x-tenant-id) | `d9990247` |
92
- | `ENV` | Environment (x-env) | `dev` \| `prod` |
93
- | `SERVICE_KEY` | Service key for internal API auth | (from Amaster console) |
138
+ Existing constructor arguments remain accepted for compatibility. New application code only needs the domain and the credentials appropriate to its operations.
94
139
 
95
140
  ## API Overview
96
141
 
@@ -241,7 +286,8 @@ All types are exported from the package. Key ones:
241
286
 
242
287
  | Type | Use case |
243
288
  |------|----------|
244
- | `AdminSDKOptions` | Constructor options |
289
+ | `AdminSDKConfiguration` | Constructor input, including APP_URL-derived domain-only initialization |
290
+ | `AdminSDKOptions` | Existing legacy options type, retained for source compatibility |
245
291
  | `CheckPermissionParams`, `CheckPermissionResult` | `auth.checkPermission` |
246
292
  | `CreateUserParams`, `CreateUserResult`, `UserDetail` | User CRUD |
247
293
  | `RoleAssignParams`, `Role` | Role assignment (use `assigneeUid` for users) |
@@ -286,3 +332,9 @@ not a numeric database ID. Identical bindings are idempotent; conflicts return
286
332
  supported. Use verified member IDs from the intended enterprise; this operation
287
333
  does not fetch WeCom contact information or prove membership. Deploy the
288
334
  matching Runtime endpoint before using the method.
335
+
336
+ ## Backend integration tests
337
+
338
+ Set ADMIN_BASE_URL to the actual application URL derived from APP_URL and ADMIN_SERVICE_KEY to that application's server-side APP_SECRET. No appId/env test option is required. The tests fail with a configuration error when no application URL is supplied; they do not silently target a shared service address.
339
+
340
+ For the owned cross-service fixture, run `TENANCY_COMPOSE_SDK=1 python3 scripts/verify-tenancy-compose.py` in the Runtime repository. It creates a temporary ordinary application, root department, system role and service key, then runs all five backend suites and the existing unit suites through real Traefik/TLS domain routing. Backend tests are not disabled in this mode. Task databases, credentials and containers are cleaned afterward.