@bearei/contracts 2.2.0 → 2.2.1

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project are documented in this file. The format is b
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.2.1 — 2026-10-28
+
+### Fixed
+
+- README now documents the release flow and states that the package declares no runtime or peer
+  dependencies; the Chinese README matches the English one again.
+- `ApiErrorBody` is documented as the business error body. Validation errors keep the NestJS
+  default body and are not assignable to it. No exported value or type changed.
+
 ## 2.2.0 — 2026-10-27
 
 ### Added

package/README.md

@@ -8,7 +8,7 @@ English | [中文](./README.zh-CN.md)
 | Export                                                 | Kind  | Purpose                                             |
 | ------------------------------------------------------ | ----- | --------------------------------------------------- |
 | `HTTP_EXCEPTION_CODE`, `HttpExceptionCode`             | value | Numeric error codes shared by services and clients  |
-| `ApiErrorBody`                                         | type  | Normalized error body `{code, message, statusCode}` |
+| `ApiErrorBody`                                         | type  | Business error body `{code, message, statusCode}`   |
 | `DEFAULT_PAGE_SIZE`, `MAX_PAGE_SIZE`                   | value | Paging limits used by every list endpoint           |
 | `PaginationQuery`, `PaginatedResult<T>`                | type  | Paging request fields and page envelope             |
 | `RESERVED_REQUEST_HEADER`, `ReservedRequestHeaderName` | value | Headers set by the gateway or authentication layer  |
@@ -23,6 +23,9 @@ English | [中文](./README.zh-CN.md)
 yarn add @bearei/contracts
 ```
 
+The package declares no runtime or peer dependencies, so installing it adds nothing else to your
+dependency tree.
+
 ## Usage
 
 ```ts
@@ -48,6 +51,10 @@ const page: PaginatedResult<{id: string}> = {
 }
 ```
 
+`ApiErrorBody` describes business errors raised by guards, services and shared exceptions. Request
+validation errors keep the NestJS default body (`statusCode`, `message`, `error`) and are not
+assignable to this type.
+
 ### Module formats
 
 The `exports` map resolves `import` consumers to the ESM build and `require` consumers to the
@@ -75,3 +82,22 @@ yarn install
 yarn verify       # format + lint + typecheck + coverage + build
 yarn run pack   # pack once and inspect the tarball
 ```
+
+## Release
+
+Releases are tag-driven. Bump `version` in `package.json`, update `CHANGELOG.md`, then push a
+matching tag (`2.2.1` and `v2.2.1` are both accepted). The tag must equal the package version;
+stable tags must be on `main`, and prerelease tags must be on `main` or `develop`.
+
+`.github/workflows/release.yml` then:
+
+1. runs `yarn verify`;
+2. packs the tarball once and verifies its file list and export map;
+3. publishes that tarball through npm Trusted Publishing (OIDC), using `latest` for stable versions
+   and `next` for prereleases such as `2.3.0-rc.1`;
+4. downloads the published tarball from the registry and verifies it again;
+5. creates a GitHub Release with the tarball attached as `bearei-contracts-<version>.tgz` (marked
+   pre-release when the dist-tag is `next`).
+
+Register this GitHub repository, the `release.yml` workflow and the `npm` environment as a trusted
+publisher for `@bearei/contracts` on npmjs.com. `workflow_dispatch` reruns an existing tag.

package/README.zh-CN.md

@@ -8,7 +8,7 @@ ESM 与 CommonJS 两种产物。
 | 导出                                                   | 类型 | 用途                                     |
 | ------------------------------------------------------ | ---- | ---------------------------------------- |
 | `HTTP_EXCEPTION_CODE`、`HttpExceptionCode`             | 值   | 服务与客户端共享的数字错误码             |
-| `ApiErrorBody`                                         | 类型 | 统一错误体 `{code, message, statusCode}` |
+| `ApiErrorBody`                                         | 类型 | 业务错误体 `{code, message, statusCode}` |
 | `DEFAULT_PAGE_SIZE`、`MAX_PAGE_SIZE`                   | 值   | 所有列表接口使用的分页上限               |
 | `PaginationQuery`、`PaginatedResult<T>`                | 类型 | 分页请求字段与分页响应信封               |
 | `RESERVED_REQUEST_HEADER`、`ReservedRequestHeaderName` | 值   | 由网关或认证层写入的保留请求头           |
@@ -23,6 +23,8 @@ ESM 与 CommonJS 两种产物。
 yarn add @bearei/contracts
 ```
 
+本包不声明任何运行时依赖或 peer 依赖，安装它不会向依赖树加入其他包。
+
 ## 使用
 
 ```ts
@@ -48,6 +50,9 @@ const page: PaginatedResult<{id: string}> = {
 }
 ```
 
+`ApiErrorBody` 对应守卫、服务与共享异常抛出的业务错误。请求参数校验错误仍使用 NestJS 标准体
+（`statusCode`、`message`、`error`），不能赋值给该类型。
+
 ### 模块格式
 
 `exports` 映射会让 `import` 使用 ESM 产物、`require` 使用 CommonJS 产物；TypeScript 会自动选择
@@ -72,6 +77,25 @@ const page: PaginatedResult<{id: string}> = {
 
 ```bash
 yarn install
-yarn verify       # lint + typecheck + 覆盖率 + 构建
+yarn verify       # 格式 + lint + typecheck + 覆盖率 + 构建
 yarn run pack   # 打包一次并检查 tarball
 ```
+
+## 发布
+
+发布由版本 tag 驱动。先修改 `package.json` 的 `version` 并更新 `CHANGELOG.md`，再推送同版本 tag
+（`2.2.1` 与 `v2.2.1` 均可）。tag 必须等于包版本；稳定版 tag 必须位于 `main`，预发布 tag 必须位于
+`main` 或 `develop`。
+
+`.github/workflows/release.yml` 随后会：
+
+1. 执行 `yarn verify`；
+2. 打包一次并校验 tarball 的文件清单与导出映射；
+3. 通过 npm Trusted Publishing（OIDC）发布该 tarball，稳定版使用 `latest`，预发布（如
+   `2.3.0-rc.1`）使用 `next`；
+4. 从 registry 下载已发布的 tarball 并再次校验；
+5. 创建 GitHub Release，附件为 `bearei-contracts-<version>.tgz`（dist-tag 为 `next` 时标记为
+   pre-release）。
+
+发布前需在 npmjs.com 上为 `@bearei/contracts` 登记本 GitHub 仓库、`release.yml` 工作流与 `npm`
+环境作为 trusted publisher。`workflow_dispatch` 可用已有 tag 手动重跑。

package/dist/index.d.mts

@@ -40,7 +40,8 @@ declare const HTTP_EXCEPTION_CODE: {
 type HttpExceptionCode = (typeof HTTP_EXCEPTION_CODE)[keyof typeof HTTP_EXCEPTION_CODE];
 
 /**
- * Normalized error body returned by Bearei HTTP APIs.
+ * Business error body returned by Bearei HTTP APIs. Validation errors keep the NestJS default
+ * body (`statusCode`, `message`, `error`) and are not represented by this type.
  * Services may return codes outside `HTTP_EXCEPTION_CODE`, so `code` stays numeric.
  */
 interface ApiErrorBody {
@@ -73,6 +74,7 @@ type Order = (typeof ORDER)[keyof typeof ORDER];
 
 declare const DEFAULT_PAGE_SIZE = 10;
 declare const MAX_PAGE_SIZE = 1024;
+
 interface PaginationQuery {
     page?: number;
     pageSize?: number;

package/dist/index.d.ts

@@ -40,7 +40,8 @@ declare const HTTP_EXCEPTION_CODE: {
 type HttpExceptionCode = (typeof HTTP_EXCEPTION_CODE)[keyof typeof HTTP_EXCEPTION_CODE];
 
 /**
- * Normalized error body returned by Bearei HTTP APIs.
+ * Business error body returned by Bearei HTTP APIs. Validation errors keep the NestJS default
+ * body (`statusCode`, `message`, `error`) and are not represented by this type.
  * Services may return codes outside `HTTP_EXCEPTION_CODE`, so `code` stays numeric.
  */
 interface ApiErrorBody {
@@ -73,6 +74,7 @@ type Order = (typeof ORDER)[keyof typeof ORDER];
 
 declare const DEFAULT_PAGE_SIZE = 10;
 declare const MAX_PAGE_SIZE = 1024;
+
 interface PaginationQuery {
     page?: number;
     pageSize?: number;

package/dist/index.js

@@ -31,7 +31,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/error-code.ts
+// src/error-code.enum.ts
 var HTTP_EXCEPTION_CODE = {
   ACCESS_DENIED_FOR_GUEST: 401003,
   APPLE_IAP_TRANSACTION_NOT_COMPLETED: 403004,
@@ -68,7 +68,7 @@ var HTTP_EXCEPTION_CODE = {
   USER_DEACTIVATED: 401005
 };
 
-// src/header.ts
+// src/header.enum.ts
 var RESERVED_REQUEST_HEADER = {
   CLIENT: "x-bearei-client",
   DOMAIN_ID: "x-bearei-domain-id",
@@ -78,23 +78,23 @@ var RESERVED_REQUEST_HEADER = {
   SUBSCRIPTION: "x-bearei-subscription"
 };
 
-// src/language.ts
+// src/language.enum.ts
 var LANGUAGE = {
   EN_US: "EN_US",
   ZH_CN: "ZH_CN"
 };
 
-// src/order.ts
+// src/order.enum.ts
 var ORDER = {
   ASC: "ASC",
   DESC: "DESC"
 };
 
-// src/pagination.ts
+// src/pagination.const.ts
 var DEFAULT_PAGE_SIZE = 10;
 var MAX_PAGE_SIZE = 1024;
 
-// src/permission.ts
+// src/permission.enum.ts
 var PERMISSION = {
   ACTION_LOG_CREATE: "action-log:create",
   ACTION_LOG_DELETE: "action-log:delete",
@@ -166,7 +166,7 @@ var PERMISSION = {
   VERSION_LOG_UPDATE: "version-log:update"
 };
 
-// src/subscription-feature.ts
+// src/subscription-feature.enum.ts
 var SUBSCRIPTION_FEATURE = {
   BOOKMARK_CLOUD_SYNC: "bookmark:cloud_sync",
   CARTON_CLOUD_SYNC: "bookmark:carton_cloud_sync",

package/dist/index.mjs

@@ -1,4 +1,4 @@
-// src/error-code.ts
+// src/error-code.enum.ts
 var HTTP_EXCEPTION_CODE = {
   ACCESS_DENIED_FOR_GUEST: 401003,
   APPLE_IAP_TRANSACTION_NOT_COMPLETED: 403004,
@@ -35,7 +35,7 @@ var HTTP_EXCEPTION_CODE = {
   USER_DEACTIVATED: 401005
 };
 
-// src/header.ts
+// src/header.enum.ts
 var RESERVED_REQUEST_HEADER = {
   CLIENT: "x-bearei-client",
   DOMAIN_ID: "x-bearei-domain-id",
@@ -45,23 +45,23 @@ var RESERVED_REQUEST_HEADER = {
   SUBSCRIPTION: "x-bearei-subscription"
 };
 
-// src/language.ts
+// src/language.enum.ts
 var LANGUAGE = {
   EN_US: "EN_US",
   ZH_CN: "ZH_CN"
 };
 
-// src/order.ts
+// src/order.enum.ts
 var ORDER = {
   ASC: "ASC",
   DESC: "DESC"
 };
 
-// src/pagination.ts
+// src/pagination.const.ts
 var DEFAULT_PAGE_SIZE = 10;
 var MAX_PAGE_SIZE = 1024;
 
-// src/permission.ts
+// src/permission.enum.ts
 var PERMISSION = {
   ACTION_LOG_CREATE: "action-log:create",
   ACTION_LOG_DELETE: "action-log:delete",
@@ -133,7 +133,7 @@ var PERMISSION = {
   VERSION_LOG_UPDATE: "version-log:update"
 };
 
-// src/subscription-feature.ts
+// src/subscription-feature.enum.ts
 var SUBSCRIPTION_FEATURE = {
   BOOKMARK_CLOUD_SYNC: "bookmark:cloud_sync",
   CARTON_CLOUD_SYNC: "bookmark:carton_cloud_sync",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bearei/contracts",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Framework-agnostic wire contracts shared by Bearei services, clients and apps",
   "keywords": [
     "bearei",