@ ciramaciel/ 合同
一个响应信封,一个封闭的错误代码目录,以及帮助 在外面回答,这是不可能的.
这个包是 可执行文件 规范:要导入哪些服务 回答,以及要检查需要导入的测试。 它执行的规则是 说明如下.
安装
bun add @ciromaciel/contract
zod 是一个 选项 ,仅由 /schemas 入境点,以及
jose 只有通过 /token。 。 。 .
快开始
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
import { errorSchema, collectionSchema, resourceSchema, pageSchema, codeSchema } from '@ciromaciel/contract/schemas'
从读者的角度讲,Zodschemas是为了同样的规则. 此路径是分开的
目的 : schemas.js 进口Zod,以及一个只需要回应的工人
无需装入它从不拨打的验证器。 指数重新出口时
计划,进口是迫切的——要求 failure 把佐德拉进来,然后..
安装失败 "找不到软件包'zod'" 任何对待同伴的人
作为可选的.
@ciromaciel/contract/plan
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
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,<base64 HMAC-SHA256 of "id.timestamp.body">,则
键为后面的基数64 whsec_5分钟以上的休息时间
拒绝. verifyWebhook 需要数个秘密,所以旋转有一个宽限期,
和有正当理由的回答stale_timestamp, (中文(简体) ), bad_signature,而不是一个
赤裸的布尔。 还有出口 signWebhook, (中文(简体) ), secretPrefixOf 财务报告和审定财务报表
SIGNATURE_TOLERANCE_SECONDS。 。 。 .
@ciromaciel/contract/token
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
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
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):它的线程是 <product>:<uuid> (单位:千美元) workKey 联 合 国 feedback.created),大楼的消息是: { id, status, note? },并有一个前缀,一个代码,一发子弹或一个未知的ID回答相同的404. 任务线本身由自己的UUID( 2.1.0): feedback.job 事件携带 workId (从"网友") workId从没有钥匙. <prefix>-<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); 移动主机的共享产品部署组.
链接
麻省理工学院 西罗·塞萨尔·马西埃尔