# @authup/core-http-kit 中文文档

规范地址：https://npmcn.com/package/%40authup/core-http-kit/

版本：1\.0\.0-beta\.73
npm 元数据更新时间：2026-11-01T20:46:42.432Z
中文译文更新时间：2026-11-07T06:16:36.500Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40authup/core-http-kit
原文对照：https://npmcn.com/package/%40authup/core-http-kit/?lang=original
项目主页：https://github.com/authup/authup#readme
源码仓库：https://github.com/authup/authup

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

- 包体积（解压后）：575 kB，301 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26\.0\.0
- 运行依赖：9 个
- 首次发布：2024-05-08T08:30:19.659Z
- 最新版本发布：2026-11-01T20:46:42.078Z
- 近 30 天下载量：4000（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 44 个）

## 中文简介

为 Authup API 键入了 HTTP 客户端,带有一个得到并刷新令牌的钩子.

## 安装

```sh
npm install @authup/core-http-kit
```

也可以使用：`pnpm add @authup/core-http-kit`、`yarn add @authup/core-http-kit`、`bun add @authup/core-http-kit`

## README

![Authup logo](https://raw.githubusercontent.com/authup/authup/master/.github/assets/logo.svg)

# @authup/core-http-kit (英语)

**为 Authup API 键入了 HTTP 客户端,带有一个得到并刷新令牌的钩子.**  
停止对 Authup 服务器进行手写取呼叫、查询字符串和更新 .

[![npm version](https://img.shields.io/npm/v/@authup/core-http-kit)](https://www.npmjs.com/package/@authup/core-http-kit) [![CI](https://github.com/authup/authup/actions/workflows/main.yml/badge.svg)](https://github.com/authup/authup/actions/workflows/main.yml) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://npmcn.com/package/%40authup/core-http-kit/LICENSE)

[**安装**](https://npmcn.com/package/%40authup/core-http-kit/#readme-installation) • 妇女 [使用量](https://npmcn.com/package/%40authup/core-http-kit/#readme-usage) • 妇女 [API 密码](https://npmcn.com/package/%40authup/core-http-kit/#readme-api) • 妇女 [文档](https://authup.org/)

* * *

## 为什么?

Authup的管理API及其OAuth2端点都是平面HTTP,因此任何客户端都可行. 否则您自己会写到请求周围的部分:每个实体的URL, rapiq查询字符串 `{ data, meta }` 响应形状、 符号赠与和 符号过期时的重试.

| 关切 | 没有它 | 用这个 |
| --- | --- | --- |
| **终点** | 每个呼叫的 URL 和响应类型 | `client.user.getMany()`, (中文(简体) ), `client.role.create()`,... 每个实体一个子API,按域类型键入 `@authup/core-kit` |
| **查询** | 编码 `filter`, (中文(简体) ), `sort`, (中文(简体) ), `fields`, (中文(简体) ), `include` 财务报告和审定财务报表 `page` 手动 | 过 `filters`, (中文(简体) ), `sorts`, (中文(简体) ), `fields`, (中文(简体) ), `relations`, (中文(简体) ), `pagination`这是给你的序列 |
| **键** | 通话 `/token`,存储符号,设置信头 | `client.token.createWithPassword()` 和兄弟姐妹,加 `ClientAuthenticationHook` |
| **过期** | 抓一个 `401`,更新,重放 | 钩子更新在一 `401` 或符号出错并重放请求一次 |
| **测试** | 嘲笑 `fetch` | `createFakeClient()` 从 `@authup/core-http-kit/testing` 按路径的答案 |

## 安装

```shell
npm install @authup/core-http-kit
```

仅限无害环境管理。 节点.js `>=26.0.0`浏览器 `fetch`。没有同伴依赖关系.

## 使用量

### 创建客户端

```typescript
import { Client } from '@authup/core-http-kit';

const client = new Client({ baseURL: 'https://auth.example.com' });

const { data: users, meta } = await client.user.getMany({
    filters: { realmId: '<realm id>' },
    sorts: { name: 'ASC' },
    pagination: { limit: 20 },
});
// meta.total, meta.schema

const { data: user } = await client.user.getOne(users[0].id);
```

-   `baseURL` 没有默认 : `Client` 发送相对的 URL, 除非你设置它 . `API_URL_DEFAULT` (单位:千美元)`http://localhost:3001`)为想要倒计时的呼叫者导出.
-   集合读取答案 `{ data: T[], meta: { total, limit?, offset?, schema? } }`。记录读取和每个字母回答 `{ data: T, meta }`。 。 。 .
-   查询需要 `filters`, (中文(简体) ), `sorts`, (中文(简体) ), `fields`, (中文(简体) ), `relations` 财务报告和审定财务报表 `pagination`,或已经组装的 rapiq `IQuery` (例如,一个与 `and()` 编号 : `or()` 从 `@rapiq/core`) (中文(简体) ). 服务器会放弃实体计划所不允许的一切; `meta.schema` 列出它的工作.

### 实体 APIs

每个实体在客户端上都有子API. 大多数动词带有相同的动词:

| 动词 | 请求 |
| --- | --- |
| `getMany(query?)` | `GET /<collection>` |
| `getOne(id, query?)` | `GET /<collection>/:id` |
| `create(data)` | `POST /<collection>` |
| `update(id, data)` | `POST /<collection>/:id` |
| `createOrUpdate(idOrName, data)` | `PUT /<collection>/:idOrName` (真人、客户、角色、范围、用户、授权、身份提供者) |
| `delete(id)` | `DELETE /<collection>/:id` |
| `getStats(query?)` | `GET /<collection>/@stats`,分组计数(realm,客户端,范围,身份提供者,密钥,信任锚地,用户,路径,角色,政策,权限,会话,事件) |
| `getSchema()` | `GET /<collection>/@schema`,可查询词汇表(除 `userAuthenticator`(中文(简体) ) |

并不是每个实体都提供每个动词:只读事件,只读会话和会话符号(加) `deleteMany`),相交点,例如: `userRole` 或者说 `clientScope` 携带无 `update`。一些额外携带,例如 `client.client.rotateSecret(id, payload?)`, (中文(简体) ), `client.session.deleteMany(query?)` 财务报告和审定财务报表 `client.realm.getOne(id)`,其 `meta.endpoints` 拥有王国 `issuer`, (中文(简体) ), `openidConfiguration` 财务报告和审定财务报表 `jwks` URLs (英语).

按实体类型选择子API, 使用 `pickEntityAPI`。每个动词在结果上都是可选的,所以每个方法都注意:

```typescript
import { EntityType } from '@authup/core-kit';
import { pickEntityAPI } from '@authup/core-http-kit';

const api = pickEntityAPI(client, EntityType.ROLE);
if (api && api.getMany) {
    const { data: roles } = await api.getMany({ pagination: { limit: 10 } });
}
```

### 获取一个符号

`client.token` 覆盖 `/token` 结束点 :

```typescript
const grant = await client.token.createWithPassword({
    username: 'admin',
    password: 'start123',
    realm_name: 'master',
});

client.setAuthorizationHeader({ type: 'Bearer', token: grant.access_token });
```

| 方法 | 赠款 |
| --- | --- |
| `createWithPassword({ username, password, otp?, realm_id?, realm_name? })` | `password` |
| `createWithClientCredentials({ client_id, client_secret })` | `client_credentials` |
| `createWithRefreshToken({ refresh_token })` | `refresh_token` |
| `createWithAuthorizationCode({ code, redirect_uri, code_verifier? })` | `authorization_code` |
| `createWithDeviceCode({ device_code, client_id? })` | `urn:ietf:params:oauth:grant-type:device_code` |
| `introspect({ token })` | `POST /token/introspect` |
| `revoke({ token })` | `POST /token/revoke` |

持有第二个系数的用户添加 `otp` (一个TOTP或恢复代码)到密码授权.

### 保持新标志

`ClientAuthenticationHook` 附加到一个或多个客户端, 当服务器要求一个时会获得一个符号 :

```typescript
import { Client, ClientAuthenticationHook, createClientTokenCreator } from '@authup/core-http-kit';

const client = new Client({ baseURL: 'https://auth.example.com' });

const hook = new ClientAuthenticationHook({
    tokenCreator: createClientTokenCreator(
        { id: '<client id>', secret: '<client secret>' },
        { client: { baseURL: 'https://auth.example.com' } },
    ),
});
hook.attach(client);
```

-   钩子没有在前面取出一个符号。 第一项请求没有提出;a `401` (或体中符号错误代码) `tokenCreator`组合 `Authorization: Bearer` 并重放请求一次.
-   同时发生的失败共用一个 `tokenCreator` 电话.
-   与 `timer` (默认情况下)它再次续约 60秒前 `expires_in` 跑出来.
-   密钥出错( N)`JWK_*` 代码)不设置头并拒绝不更新;失败的更新也会不设置.
-   `createUserTokenCreator({ name, password, realmId?, realmName? }, { client })` 是密码授予对应的。 你可以通过任何 `() => Promise<OAuth2TokenGrantResponse>` 换句话说.
-   钩子发出 `refreshFinished`, (中文(简体) ), `refreshFailed`, (中文(简体) ), `headerSet` 财务报告和审定财务报表 `headerRemoved` (单位:千美元)`ClientAuthenticationHookEventName`) (中文(简体) ).

### 设备授权

一个没有浏览器的设备 要求一个代码,显示它,和民调:

```typescript
import { isClientError } from '@authup/core-http-kit';

const device = await client.deviceAuthorization.create({ client_id: '<client id>', scope: 'openid' });
console.log(`Open ${device.verification_uri_complete}`);

async function poll(interval: number) {
    await new Promise((resolve) => { setTimeout(resolve, interval * 1000); });
    try {
        return await client.token.createWithDeviceCode({
            device_code: device.device_code,
            client_id: '<client id>',
        });
    } catch (e) {
        const error = isClientError(e) ? e.response?.data?.error : undefined;
        if (error === 'authorization_pending') return poll(interval);
        if (error === 'slow_down') return poll(interval + 5);
        throw e;
    }
}

const grant = await poll(device.interval);
```

`client.deviceAuthorization.lookup / approve / deny({ user_code })` 是批准代码的页面的呼叫;它们骑着客户自己的持单人.

### 检查权限

`client.authorization.check()` 询问哪个服务器允许呼叫者持有, 以及哪个域:

```typescript
const permissions = await client.authorization.check({ names: ['user_read', 'user_update'] });
const canUpdate = permissions.some((permission) => permission.name === 'user_update');
```

-   奥米 `names` 检查所有许可. `realms` 财务报告和审定财务报表 `clients` 选择哪个定义由域和拥有定义的客户端进行评估;两者都默认为 `[null]` (定义由无域和无客户所有). 过 `own` (你的地盘,或者客户 你的令牌是发给), `ownOrNull` (加上未拥有), `granted` (加上你持有的每一项定义的拥有者)或身份证明清单(`null` . . . .
-   `targetRealms` 选择每个定义对照的资源域。 默认为 `ownOrNull` (呼叫方域加全球行); 通过 `own` 或 域 id 列表 (`null` (单位:千美元).
-   每个条目都包含 `name`,拥有 `realmId` 编号 : `clientId` (无效时允许)和 `targetRealms` 它能撑住 只有呼叫者在至少一个被请求的目标域中持有的定义才会出现,因此不存在拒绝的手段.
-   `checkWithMaxAge()` ưμ㼯a `maxAge`,直到日期或时间政策的秒数可以改变答案.
-   `client.authorization.get()` 读取无身份许可目录。 它需要一个 `permission_read`, (中文(简体) ), `permission_update` 或者说 `permission_delete`。 。 。 .

### 测试

```typescript
import { createFakeClient } from '@authup/core-http-kit/testing';

const fake = createFakeClient({
    handlers: {
        'GET /users/:id': (req) => ({ data: { id: req.params.id, name: 'alice' }, meta: {} }),
    },
});

const { data } = await fake.user.getOne('1');
// fake.requests lists every request: method, url, body, params, headers
```

-   处理器密钥是 `'<METHOD> <path>'` 与 `:param` 部分,或 `'*'` 做为包罗万象.
-   未匹配的请求答案 `fallback`,默认情况下 `{ data: [], meta: { total: 0 } }`。 。 。 . `baseURL` 默认为 `http://fake.test`。 。 。 .
-   Urlencoded body (token requests) 被记录为普通对象.

## 选项

`ClientAuthenticationHookOptions`数字 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `tokenCreator` | `() => Promise<OAuth2TokenGrantResponse>` | 所需经费 | 需要签章时打电话 |
| `timer` | `boolean` | `true` | 在信使到期前60秒续签 |
| `baseURL` | `string` |  | 接受兼容性; 钩子没有读取 |

`Client` 选择 hapic 的客户端选项(`baseURL`, (中文(简体) ), `headers`(中文(简体) ).

## API 密码

| 导出 | 仁爱 | 目的 |
| --- | --- | --- |
| `Client`, (中文(简体) ), `IClient` | 类,接口 | HTTP客户及其合同,每个实体和工作流程有一个子API |
| `ClientAuthenticationHook` | 类 | 为附属客户获取、更新和应用代号 |
| `ClientAuthenticationHookEventName` | 语句 | 钩子发射事件 |
| `createClientTokenCreator`, (中文(简体) ), `createUserTokenCreator` | 函数 | 客户证书和密码证书的创建者 |
| `TokenCreator` | 类型 | `() => Promise<OAuth2TokenGrantResponse>` |
| `pickEntityAPI` | 函数 | 以 `EntityType` 字符串 |
| `EntityAPIDispatch`, (中文(简体) ), `ClientEntityAPIKey` | 类型 | 动词可选表面 `pickEntityAPI` 返回,并输入它接受的密钥 |
| `EntityRecordResponse`, (中文(简体) ), `EntityCollectionResponse` | 类型 | 这个 `{ data, meta }` 响应形状 |
| `EntityStatsQuery`, (中文(简体) ), `EntityStatsResponse`, (中文(简体) ), `buildStatsURL` | 类型,函数 | 这个 `@stats` 读取 |
| `EntityQueryInput`, (中文(简体) ), `buildQueryString` | 类型,函数 | 每个读取的查询输入及其 URL 序列化 |
| `UserAPI`, (中文(简体) ), `RoleAPI`, (中文(简体) ), `OAuth2TokenAPI`, (中文(简体) ), `AuthorizationAPI`,, , , , , , , , . | 类 | 子APIs,每个有 `I*API` 接口和 `*CreatePayload` 编号 : `*UpdatePayload` 类型 |
| `AuthorizeInfo`, (中文(简体) ), `ClientSummary`, (中文(简体) ), `RealmSummary`, (中文(简体) ), `StatusResponse` | 类型 | 工作流程响应形状 |
| `isClientError`, (中文(简体) ), `getClientErrorCode` | 函数 | 探测出一个黑道 `ClientError` 读它 `code` |
| `setHeader`, (中文(简体) ), `unsetHeader` | 函数 | 信头助手从 hapic 再出口 |
| `CookieName` | 语句 | 饼干名称 Authup 网络套件在下面存储符牌 |
| `API_URL_DEFAULT` | 针头 | `http://localhost:3001` |

`@authup/core-http-kit/testing` 出口 `FakeClient`, (中文(简体) ), `createFakeClient`, (中文(简体) ), `matchRoute` 编辑 `Fake*` 类型.

## 页:1

-   **Token 调用客户端 `Authorization` 头曰.** `client.token.*` 财务报告和审定财务报表 `client.deviceAuthorization.create` 移除客户所携带的头条,因此体内的客户证书从不与持证人相混. 过 `{ authorizationHeaderInherit: true }` (或 `{ authorizationHeader }`作为第二个送出一个论点的论据,例如用你自己的证书进行回顾: `client.token.introspect({ token }, { authorizationHeaderInherit: true })`。 。 。 .
-   **错误消息来自服务器 .** 如果请求失败, 客户端将替换错误 `message` 与身体的 `message` 当它有一个,所以 URL 已经不在它.
-   **刷新每一次.** 如果重播的请求再次失败, 它的错误会到达您手中 .

## 许可证

由 所制

现按 [Apache 2.0 许可证](https://npmcn.com/package/%40authup/core-http-kit/LICENSE)。 。 。 .

## 常见问题

### @authup/core-http-kit 是什么？

为 Authup API 键入了 HTTP 客户端,带有一个得到并刷新令牌的钩子\.

### 如何安装 @authup/core-http-kit？

在项目目录运行 npm install @authup/core-http-kit，或使用 pnpm add / yarn add / bun add。

### @authup/core-http-kit 支持 TypeScript 吗？

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

### @authup/core-http-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @authup/core-http-kit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @authup/core-http-kit 可以商用吗？

@authup/core-http-kit 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @authup/core-http-kit 的下载量有多少？

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

### @authup/core-http-kit 还在维护吗？

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