# @ciromaciel/contract 中文文档 规范地址：https://npmcn.com/package/%40ciromaciel/contract/ 版本：2\.2\.0 npm 元数据更新时间：2026-11-05T09:41:55.507Z 中文译文更新时间：2026-11-09T17:06:24.792Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40ciromaciel/contract 原文对照：https://npmcn.com/package/%40ciromaciel/contract/?lang=original 项目主页：https://ciromaciel.click/ ## 关键信息（来自 npm 元数据） - 包体积（解压后）：110 kB，15 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：0 个 - peer 依赖：zod ^4\.0\.0，jose ^5\.0\.0 \|\| ^6\.0\.0 - 首次发布：2026-09-20T14:41:03.507Z - 最新版本发布：2026-11-05T09:41:55.299Z - 近 30 天下载量：2230（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：14（近 12 个月 14 个） ## 中文简介 一个单一的响应信封,一个封闭的错误代码目录,以及让外部无法回答的帮助者. ## 安装 ```sh npm install @ciromaciel/contract ``` 也可以使用：`pnpm add @ciromaciel/contract`、`yarn add @ciromaciel/contract`、`bun add @ciromaciel/contract` ## README # @ ciramaciel/ 合同 一个响应信封,一个封闭的错误代码目录,以及帮助 在外面回答,这是不可能的. 这个包是 **可执行文件** 规范:要导入哪些服务 回答,以及要检查需要导入的测试。 它执行的规则是 说明如下. ## 安装 ```bash bun add @ciromaciel/contract ``` `zod` 是一个 **选项** ,仅由 `/schemas` 入境点,以及 `jose` 只有通过 `/token`。 。 。 . ## 快开始 ```js import { ok, created, collection, failure } from '@ciromaciel/contract' import { CODES } from '@ciromaciel/contract/codes' return ok({ id, name }) return created({ id, name }) return failure(CODES.NOT_FOUND, 'project not found') ``` `failure()` 从代码中获取 HTTP 状态—— 没有签名 让你回来 `NOT_FOUND` 有200块. ## API 密码 ### `@ciromaciel/contract` | 导出 | 它会做什么 | | --- | --- | | `ok(resource, { status, headers })` | 一个资源,在根源。 没有 `data`,没有 `success`,没有 `message`。 。 。 . | | `created(resource, { headers })` | 刚刚诞生的资源——201. | | `collection(list, page, { status, headers })` | `{ items, page: { limit, offset, total, hasMore } }`没有 `total`, (中文(简体) ), `total` 财务报告和审定财务报表 `hasMore` 回来 `null` ——"无人计"与"零"不同. | | `page({ limit, offset, total, extra })` | 构建 `page` 对象用于 `collection`,需要数字 `total`。 。 。 . | | `pagination(url, { defaultLimit, maxLimit })` | 读取 `limit`编号 :`offset` 从 URL 有上限. | | `failure(code, message, { details, headers, status })` | 错误 `Response`状态来自代码. | | `failureBody(code, message, details)` | `{ body, status }` 用于将反应本身汇集在一起的框架. | | `failureWithStatus(status, message, details, headers)` | 对于一个只有HTTP号码的全局错误处理器. | | `CODES` • 妇女 `STATUS_BY_CODE` • 妇女 `RETRIABLE` • 妇女 `ALIASES` | 词汇及其表. | | `isCode` • 妇女 `toCode` • 妇女 `codeFromStatus` | 代码警卫和转换. | ### `@ciromaciel/contract/codes` 关闭的电源: `UNAUTHORIZED`, (中文(简体) ), `FORBIDDEN`, (中文(简体) ), `WRONG_AUDIENCE`, (中文(简体) ), `INSUFFICIENT_SCOPE`, (中文(简体) ), `NOT_FOUND`, (中文(简体) ), `CONFLICT`, (中文(简体) ), `NAME_TAKEN`, (中文(简体) ), `EXPIRED`, (中文(简体) ), `HAS_RESOURCES`, (中文(简体) ), `VALIDATION_ERROR`, (中文(简体) ), `UNPROCESSABLE`, (中文(简体) ), `RATE_LIMITED`, (中文(简体) ), `PAYLOAD_TOO_LARGE`, (中文(简体) ), `PLAN_LIMIT`, (中文(简体) ), `SUBSCRIPTION_REQUIRED`, (中文(简体) ), `INTERNAL_ERROR`, (中文(简体) ), `SERVICE_UNAVAILABLE`, (中文(简体) ), `UPSTREAM_ERROR`。 。 。 . `code` 客户端读取的部分; `message` 人类及其语言 可随时更改。 重编代码是突破性的改变. ### `@ciromaciel/contract/schemas` ```js import { errorSchema, collectionSchema, resourceSchema, pageSchema, codeSchema } from '@ciromaciel/contract/schemas' ``` 从读者的角度讲,Zodschemas是为了同样的规则. 此路径是分开的 目的 : `schemas.js` 进口Zod,以及一个只需要回应的工人 无需装入它从不拨打的验证器。 指数重新出口时 计划,进口是迫切的——要求 `failure` 把佐德拉进来,然后.. 安装失败 _"找不到软件包'zod'"_ 任何对待同伴的人 作为可选的. ### `@ciromaciel/contract/plan` ```js import { createPlanGate } from '@ciromaciel/contract/plan' export const plan = createPlanGate({ product: 'auth', resource: 'applications', tiers: [ { slug: 'auth-applications-1', limit: 1 }, { slug: 'auth-applications-5', limit: 5 }, { slug: 'auth-applications-unlimited', limit: Infinity }, ], }) ``` 还有出口 `hasSlug`, (中文(简体) ), `tierLimit`, (中文(简体) ), `getPlanNotice`, (中文(简体) ), `withPlanNotice`, (中文(简体) ), `gateTelemetry`, (中文(简体) ), `recordGateDecision` 财务报告和审定财务报表 `resetGateTelemetry`。一个产品拥有 前缀,弹出和通知的措辞;缓存,倒闭, 产品前缀检查和选择 `PLAN_LIMIT` 财务报告和审定财务报表 `SUBSCRIPTION_REQUIRED` 到处都是同样的推理. ### `@ciromaciel/contract/webhooks` ```js import { webhookHeaders, verifyWebhook, generateSigningSecret } from '@ciromaciel/contract/webhooks' const headers = await webhookHeaders(secret, { id: event.id, body }) // x-ccm-id, x-ccm-timestamp, x-ccm-signature const result = await verifyWebhook([secret, previousSecret], { id, timestamp, signature, body }) ``` 堆栈的每个网页都有一个协议: 标准 Webhooks with the `x-ccm` 前缀。 签名是 `v1,`,则 键为后面的基数64 `whsec_`5分钟以上的休息时间 拒绝. `verifyWebhook` 需要数个秘密,所以旋转有一个宽限期, 和有正当理由的回答`stale_timestamp`, (中文(简体) ), `bad_signature`,而不是一个 赤裸的布尔。 还有出口 `signWebhook`, (中文(简体) ), `secretPrefixOf` 财务报告和审定财务报表 `SIGNATURE_TOLERANCE_SECONDS`。 。 。 . ### `@ciromaciel/contract/token` ```js import { createTokenVerifier } from '@ciromaciel/contract/token' const tokens = createTokenVerifier({ authUrl: 'https://auth.worker.myinfrastructure.click' }) await tokens.verifySession(bearer) // REST routes await tokens.verifyAccessToken(bearer, { audience: 'https://hoster.worker.myinfrastructure.click/mcp' }) // MCP server ``` Auth 签名会话和 OAuth 访问令牌的密钥和发行符相同; 只有权利要求才能把他们分开. `verifySession` 接受个人开庭,并 拒绝访问令牌( e)`access_token_not_accepted`:一种同意的标志 在 REST 路由中,绝不能将资源和一个范围作为整个账户. `verifyAccessToken` 只接受一个访问符,其 `aud` 是这个服务器 (单位:千美元)`wrong_audience` 否则, RFC 8707 并返回 `scopes`。 。 。 . 两个都回来 `{ ok: true, subject, email, name, scopes, claims }` 或者说 `{ ok: false, reason }`,从不放弃糟糕的证书, 并接受RS256与 页:1 `riligar-auth` 只有发行人. `jose` (5或6个) **选项** 对应, 需要 只有通过这个入口. ### `@ciromaciel/contract/outbox` ```js import { OUTBOX_SQL, envelope, enqueueEvent, deliverDue, releaseHeld, retryDelivery } from '@ciromaciel/contract/outbox' ``` 送货排队 每一个产品共享。 每次活动都是一行的 `outbox` 在它离开之前,每个指定终点一个,与 `./webhooks`。一个2xx是 `sent`;401和403为 `held` (每小时检查一次,由 `releaseHeld` - 当秘密改变时) `failed`;在1分,5分,30分,2分和12分之后,其他任何复试. `OUTBOX_SQL` 是用于产品第一次迁移的计划。 产品提供D1型 `db` 财务报告和审定财务报表 `decryptSecret(ciphertext)`。 。 。 . ### `@ciromaciel/contract/feedback` ```js import { createFeedback, FEEDBACK_SQL } from '@ciromaciel/contract/feedback' ``` "Sugerir ou relatar",每个面板的拐角按钮(`FeedbackWidget` 内 `@ciromaciel/dashboard-kit`在工人那边. `createFeedback({ product, prefix, error, requirePerson, locate, fields })` 返回时 `handleRoutes` (单位:千美元)`GET`编号 :`POST /api/feedback`在登录后, `handleHooks` (任务在 `/feedback/tasks` 和建筑工作的消息 `/feedback/build`和 `runCron` (重报任务组没有拿走的东西;重报任务组从未拿走的东西). 其全部UUID处理反馈,只有它(2.0,25/10/2026):它的线程是 `:` (单位:千美元) `workKey` 联 合 国 `feedback.created`),大楼的消息是: `{ id, status, note? }`,并有一个前缀,一个代码,一发子弹或一个未知的ID回答相同的404. 任务线本身由自己的UUID( 2.1.0): `feedback.job` 事件携带 `workId` (从"网友") `workId`从没有钥匙. `-<6 hex>` (单位:千美元)`DK-1A2B3C`)是标题中读取的标签,从来不是地址. `FEEDBACK_SQL` 表格; 产品添加自己的列(`deck_id`并把它们命名为 `locate().columns`. 只有一个人发出,和 `locate` 只有账户本身的东西。 信封 : `FEEDBACK_URL`, (中文(简体) ), `FEEDBACK_SECRET`, (中文(简体) ), `TASKS_WEBHOOK_SECRET`, (中文(简体) ), `BUILD_SECRET`。 。 。 . `FAILURE_OPTIONS` 是一份停止(1.5.0)的工作的选择:西罗人所选择的每一个都成为应答的工作(`repair`, (中文(简体) ), `retry`, (中文(简体) ), `revert`, (中文(简体) ), `ship`, (中文(简体) ), `revise`, (中文(简体) ), `build`); 移动主机的共享产品部署组. ## 链接 - [网站](https://ciromaciel.click/) - [Npm 的软件包](https://www.npmjs.com/package/@ciromaciel/contract) 麻省理工学院 [西罗·塞萨尔·马西埃尔](https://ciromaciel.click/) ## 常见问题 ### @ciromaciel/contract 是什么？ 一个单一的响应信封,一个封闭的错误代码目录,以及让外部无法回答的帮助者\. ### 如何安装 @ciromaciel/contract？ 在项目目录运行 npm install @ciromaciel/contract，或使用 pnpm add / yarn add / bun add。 ### @ciromaciel/contract 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/ciromaciel\_\_contract 是否存在。 ### @ciromaciel/contract 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @ciromaciel/contract 可以商用吗？ @ciromaciel/contract 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @ciromaciel/contract 的下载量有多少？ 根据 npm 官方下载统计，@ciromaciel/contract 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,230 次，日均约 74 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @ciromaciel/contract 还在维护吗？ 最新版本 2\.2\.0 发布于 2026/11/05（4 天前）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/09/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。