# @frontegg/e10s-client 中文文档

规范地址：https://npmcn.com/package/%40frontegg/e10s-client/

版本：4\.0\.0
npm 元数据更新时间：2026-11-05T13:39:14.895Z
中文译文更新时间：2026-11-15T14:50:11.566Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40frontegg/e10s-client
原文对照：https://npmcn.com/package/%40frontegg/e10s-client/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：953 kB，265 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：axios ^1
- 首次发布：2024-05-12T15:39:01.074Z
- 最新版本发布：2026-11-05T13:39:14.626Z
- 近 30 天下载量：12296（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 11 个）

## 中文简介



## 安装

```sh
npm install @frontegg/e10s-client
```

也可以使用：`pnpm add @frontegg/e10s-client`、`yarn add @frontegg/e10s-client`、`bun add @frontegg/e10s-client`

## README

  

![Frontegg Logo](https://fronteggstuff.blob.core.windows.net/frongegg-logos/logo-transparent.png)

### 节点JS客户端

## 目录

-   [安装](https://npmcn.com/package/%40frontegg/e10s-client/#readme-installation)
-   [先决条件](https://npmcn.com/package/%40frontegg/e10s-client/#readme-prerequisite)
-   [使用量](https://npmcn.com/package/%40frontegg/e10s-client/#readme-usage)
-   [实例](https://npmcn.com/package/%40frontegg/e10s-client/#readme-examples)
-   [查询操作](https://npmcn.com/package/%40frontegg/e10s-client/#readme-lookup-operations)
-   [监测](https://npmcn.com/package/%40frontegg/e10s-client/#readme-monitoring)

## 安装

要使用 npm 安装软件包, 请运行以下

```
$ npm install @frontegg/e10s-client
```

## 先决条件

权限客户端与 Frontegg 的 ReBAC 授权引擎交互, 以评价权限和查询访问关系 .

寻找指示 [这里](https://developers.frontegg.com/ciam/guides/authorization/entitlements/agent/setup)

## 使用量

### 初始化客户端

```typescript
import { EntitlementsClientFactory, RequestContextType } from '@frontegg/e10s-client';

const e10sClient = EntitlementsClientFactory.create({
    engineEndpoint: 'localhost:50051',
    engineToken: 'your-engine-token'
});
```

### 配置选项

```typescript
import { EntitlementsClientFactory } from '@frontegg/e10s-client';

const e10sClient = EntitlementsClientFactory.create({
    engineEndpoint: 'localhost:50051',
    engineToken: 'your-engine-token',
    logging: {
        client: customLoggingClient, // Optional: custom logging client
        logResults: true // Optional: log all query results
    },
    fallbackConfiguration: {
        // Optional: fallback behavior on errors
        defaultFallback: false
    }
});
```

### 多个Frontegg 实例

一个 SpiceDB 可以服务 Frontegg 的几个实例 。 每个案例都是卖家,SDK 名称空间每个读取到该实例的 schema 前缀, 来源于其 `vendorId` (单位:千美元)`v_` + 供应商代号 `-` 改为 `_`) (中文(简体) ). 配置实例一次, 每选一个 调用 `instanceId`数字 :

```typescript
const e10sClient = EntitlementsClientFactory.create({
    engineEndpoint: 'localhost:50051',
    engineToken: 'your-engine-token',
    instances: [
        { instanceId: 'eu', vendorId: '2f9c1a44-7b0e-4a1e-9f8a-1c2d3e4f5a6b' },
        { instanceId: 'us', vendorId: '8b1d0e77-3c5a-4f2b-9d6e-7a8b9c0d1e2f' }
    ],
    defaultInstanceId: 'eu'
});

await e10sClient.isEntitledTo(subjectContext, requestContext, { instanceId: 'us' });
```

-   `instanceId` 每一个电话都可以选择 配置一个实例,或 `defaultInstanceId` 设置, 可以省略; 否则调用 `InstanceIdRequiredException`。一个未知的ID抛出 `UnknownInstanceException`两者 扩展 `InstanceResolutionException` 他们不是被弃绝的 倒计时.
-   前缀总是来自 `vendorId` 无法直接设置。 A 类 `vendorId` 可能 仅包含 `a-z`, (中文(简体) ), `0-9` 财务报告和审定财务报表 `-`,最多为61个字符,而不是结尾为 `-`任意 其他,包括大写字母和 `_`掷出 `ConfigurationInputIsInvalidException` 当客户端被创建时。 一个 `instanceId` 必须是 `a-z`, (中文(简体) ), `0-9` 财务报告和审定财务报表 `-`, (中文(简体) ), 以字母或数字开头,以及 `legacy` 保留; 其它任何投出 `ConfigurationInputIsInvalidException` 当客户端被创建时.
-   每个案例都可能带有自己的 `fallbackConfiguration`;全客户适用 否则.
-   与 `instances` 配置, 传递给 SDK 的对象类型不得包含 `/`,因为 sDK应用了前缀本身. 此类型投出 `InvalidObjectTypeException` 从 `isEntitledTo`, (中文(简体) ), `lookupTargetEntities` 财务报告和审定财务报表 `lookupEntities` 而不是被回答 倒计时。 单位 `isEntitledToMany` 只有此项失败: 它作为 `{ result: false, error: '<reason>' }` 其它东西都还没解答,请回答 任意 `result !== true` 被否认.
-   没有 `instances` 配置, 每个读取没有前缀, 并传递有效的对象类型 通过没有改变,所以这样的类型 `acme/document` 继续工作,一个普通的名字也一样 你们自己人 `v_user`。这是一次突破性的改变 现有呼叫者在两个案例中, 两者现在都抛出 `InvalidObjectTypeException` 而不是被回答 倒置:一个不是有效 SpiceDB 名称的对象类型(见下个点),它曾经是 到达 SpiceDB 后作为已配置的倒置返回返回,并使用名称空格类型,其前缀 从保留供应商前缀开始 `v_`,例如 `v_acme/document`,所以遗留客户端可以 永远不要在共享 SpiceDB 上访问供应商的命名空间 .
-   在两种模式中,对象类型必须是有效的 SpiceDB 名称: 3到64个字符,从 `a-z`,仅包含 `a-z`, (中文(简体) ), `0-9` 财务报告和审定财务报表 `_`,结尾为 `a-z` 或者说 `0-9`在遗留模式中 a 之前的每个前缀 `/` 遵守同样的规则,但最多为63个字符。 还有什么, 例如 `Document`, (中文(简体) ), `my-entity` 或者说 `a`掷出 `InvalidObjectTypeException` 改为 将 SpiceDB 作为分析错误.
-   日志有效载荷携带已解决 `instanceId` (单位:千美元)`legacy` 否时 `instances` 已配置). `LoggingClient.log` 财务报告和审定财务报表 `LoggingClient.error` 作为可选的线索 `{ instanceId }` 参数,所以现有的执行继续工作.

#### 阅读实例计划

```typescript
const schema = await e10sClient.readSchemaFor({ instanceId: 'us' });
```

`readSchemaFor` 只返回该实例 `definition` 财务报告和审定财务报表 `caveat` 块,有它的图案 前缀从他们的名字和类型引用中删除。 这是一个只读视图:顶级 指令被删除, 因此无法写入 。 如果计划不能分割成 安全抛出 `SchemaParseException` 而不是冒险返回另一个实例 定义。 没有 `instances` 配置它只返回未设置的前缀 `definition` 财务报告和审定财务报表 `caveat` 块,没有改变, 从来没有其他供应商的前缀块.

SpiceDB没有读取部分的 schema, 所以每个调用都读取整个 组群 schema 并过滤它 在这里。 处理 `readSchemaFor` 作为行政电话,并让它远离请求路径.

### 设定主题背景

主题上下文描述执行动作的用户,如果与 Frontegg 认证,这些动作可以从 Frontegg JWT 取出

```typescript
const subjectContext: SubjectContext = {
    tenantId: 'my-tenant-id',
    userId: 'my-user-id', // Optional
    permissions: ['read', 'write'], // Optional
    attributes: { 'my-custom-attribute': 'some-value' } // Optional
};
```

### 查询

权限客户端允许您查询一个功能、权限或路由权限,每个权限都需要不同的上下文信息.

#### 特性查询

```typescript
const e10sResult = await e10sClient.isEntitledTo(subjectContext, {
    type: RequestContextType.Feature,
    featureKey: 'my-cool-feature'
});

if (!e10sResult.result) {
    console.log(`User is not entitled to "my-cool-feature" feature`);
}
```

#### 查询权限

```typescript
const e10sResult = await e10sClient.isEntitledTo(subjectContext, {
    type: RequestContextType.Permission,
    permissionKey: 'read'
});

if (!e10sResult.result) {
    console.log(`User is not entitled to "read" permission`);
}
```

#### 查询路线

```typescript
const e10sResult = await e10sClient.isEntitledTo(subjectContext, {
    type: RequestContextType.Route,
    method: 'GET',
    path: '/users'
});

if (!e10sResult.result) {
    console.log(`User is not entitled to "GET /users" route`);
}
```

#### FGA( 精密授权) 查询

```typescript
const e10sResult = await e10sClient.isEntitledTo(
    {
        entityType: 'user',
        key: 'some@user.com'
    },
    {
        type: RequestContextType.Entity,
        entityType: 'document',
        key: 'README.md',
        action: 'read'
    }
);

if (!e10sResult.result) {
    console.log(`User is not allowed to read document`);
}
```

#### FGA 有时间访问查询( 主动 提醒)

对于使用 `active_at` 要控制基于时间的访问,请指定 `at` 参数用于在特定时间点评价访问.

```typescript
const e10sResult = await e10sClient.isEntitledTo(
    {
        entityType: 'user',
        key: 'some@user.com'
    },
    {
        type: RequestContextType.Entity,
        entityType: 'document',
        key: 'README.md',
        action: 'read',
        at: '2026-01-15T12:00:00Z'
    }
);

if (!e10sResult.result) {
    console.log(`User is not allowed to read document at the specified time`);
}
```

这个 `at` 参数接受 ISO 8601 格式字符串:

-   UTC格式 : `2025-12-31T23:59:59Z`
-   时区偏移 : `2025-12-31T23:59:59+02:00`

若为 `at` 未提供,它默认为当前协调世界时的时间.

> **说明:** 这个 `at` 参数也支持在 [查询操作](https://npmcn.com/package/%40frontegg/e10s-client/#readme-lookup-operations) 同样的格式和行为.

## 实例

可运行的演示 [`examples/`](https://npmcn.com/package/%40frontegg/e10s-client/examples/)他们使用 **单独 `package.json`** 并且现在 **没有** 运行时安装 `yarn` 在雷波根.

```bash
cd examples
yarn install   # pulls @frontegg/e10s-client@latest from npm
```

见 [实例/读取](https://npmcn.com/package/%40frontegg/e10s-client/examples/Readme.md) 用于 Docker/ SpiceDB 设置和演示脚本.

## 查询操作

客户端提供查询操作,查询ReBAC授权模式,以发现实体之间的访问关系.

FGA 搜索操作支持选项 `at` 基于时间的存取控制参数(见 [基于时间的访问](https://npmcn.com/package/%40frontegg/e10s-client/#readme-query-for-fga-with-time-based-access-active_at-caveat)) (中文(简体) ).

### 查询权利

查找授予租户或用户的所有权益特征密钥.

此检索返回 **有效特征应享权利** 关于请求的主题:

-   仅当 `tenantId` 答复中载有该租户可获得的专项补助金.
-   当两者 `tenantId` 财务报告和审定财务报表 `userId` 答复中包含用户的有效特征补助金:租户继承补助金外加用户直接补助金.
-   若为 `userId` 但用户不是租户,答复是空的.
-   如果同一特性密钥通过租户和用户获得,则在页面回复中返回一次.

在需要租户级权益时,只使用租户科目. 使用主题 `userId` 当您需要适用于特定用户的特性集时.

> **贴子 :** 对于用户的查询,对租户和用户的补助金进行独立查询并发放。 通过两个流可以达到的特性密钥可能出现在不同的页面上,因此集合多页的调用者在需要时应该将特性密钥跨页复制.

```typescript
const response = await e10sClient.lookupEntitlements({
    subject: {
        tenantId: 'tenant-123',
        userId: 'user-456', // Optional: include for effective user entitlements
        attributes: { plan: 'pro' } // Optional: evaluated by targeting rules
    },
    criteria: {
        type: RequestContextType.Feature
    },
    limit: 100, // Optional: default 50
    cursor: undefined // Optional: pagination cursor
});

console.log(`Found ${response.totalReturned} entitlement features`);

response.entitlements.forEach((entitlement) => {
    console.log(`${entitlement.type}:${entitlement.key}`);
    // entitlement.permissionship: 'HAS_PERMISSION' | 'CONDITIONAL_PERMISSION' | 'NO_PERMISSION'
});

if (response.cursor) {
    const nextPage = await e10sClient.lookupEntitlements({
        // ... same params
        cursor: response.cursor
    });
}
```

### 搜索目标实体

查找一个实体(即用户)有权执行特定行动的所有目标实体实例(即文档).

```typescript
const response = await e10sClient.lookupTargetEntities({
    entityType: 'user',
    entityId: 'user-123',
    TargetEntityType: 'document',
    action: 'read',
    limit: 100, // Optional: limit number of results (default: 50, max: 1000)
    cursor: undefined, // Optional: pagination cursor
    at: '2026-01-15T12:00:00Z' // Optional: ISO 8601 timestamp for active_at caveat
});

console.log(`Found ${response.totalReturned} Target Entities`);

response.targets.forEach((target) => {
    console.log(`${target.TargetEntityType}:${target.TargetEntityId}`);
    // target.permissionship: 'HAS_PERMISSION' | 'CONDITIONAL_PERMISSION' | 'NO_PERMISSION'
});

// For pagination, use the returned cursor
if (response.cursor) {
    const nextPage = await e10sClient.lookupTargetEntities({
        // ... same params
        cursor: response.cursor
    });
}
```

### 查询实体

查找所有有资格在特定实体实例上执行特定动作的实体(即用户)(即文档)

```typescript
const response = await e10sClient.lookupEntities({
    TargetEntityType: 'document',
    TargetEntityId: 'doc-456',
    entityType: 'user',
    action: 'read',
    at: '2026-01-15T12:00:00Z'
});

console.log(`Found ${response.totalReturned} entities`);

response.entities.forEach((entity) => {
    console.log(`${entity.entityType}:${entity.entityId}`);
    // entity.permissionship: 'HAS_PERMISSION' | 'CONDITIONAL_PERMISSION' | 'NO_PERMISSION'
});
```

## 监测

如果启用了监测模式,则只记录实际结果,以下有效载荷将始终返回

```json
{
    "result": true,
    "monitoring": true
}
```

## 常见问题

### 如何安装 @frontegg/e10s-client？

在项目目录运行 npm install @frontegg/e10s-client，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：axios（^1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @frontegg/e10s-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @frontegg/e10s-client 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @frontegg/e10s-client 可以商用吗？

@frontegg/e10s-client 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @frontegg/e10s-client 的下载量有多少？

根据 npm 官方下载统计，@frontegg/e10s-client 在 2026/10/16 – 2026/11/14 这 30 天内被下载 12,296 次，日均约 410 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @frontegg/e10s-client 还在维护吗？

最新版本 4\.0\.0 发布于 2026/11/05（10 天前）；至今共发布 39 个版本，其中过去 12 个月发布了 11 个；首次发布于 2024/05/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。