@zeroxsolutions/response 0.12.1 → 0.12.2

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.12.2 (2026-09-27)
+
+### 🚀 Features
+
+- **response:** declare a refusal's Retry-After off errorResponse ([53cc8d1](https://github.com/zeroxsolutions/zeroxsolutions/commit/53cc8d1))
+- **response:** add the status a refused burst answers with ([910c52d](https://github.com/zeroxsolutions/zeroxsolutions/commit/910c52d))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
 ## 0.12.1 (2026-09-18)
 
 ### 🚀 Features

package/dist/api-response.d.ts

@@ -4,7 +4,8 @@ import { errorDocumentSchema } from './errors/index.js';
 import { JSON_API_MEDIA_TYPE } from './media-type.js';
 import type { JsonApiResource } from './resource.js';
 /**
- * An OpenAPI response object for this spelling - one media type, one schema.
+ * An OpenAPI response object for this spelling - one media type, one schema, and the `Retry-After` a
+ * refusal that tells its caller how long to wait declares.
  *
  * Exported because a consumer emitting declarations has to NAME it: a route built from these helpers
  * is an exported const whose type mentions it, and a private one fails that emit with TS4023.
@@ -14,9 +15,34 @@ export interface JsonApiResponse<S extends ZodType> {
     content: Record<typeof JSON_API_MEDIA_TYPE, {
         schema: S;
     }>;
+    headers?: {
+        'Retry-After': RetryAfterHeader;
+    };
 }
-/** The response object for a failure status - the `errors[]` document. */
-export declare function errorResponse(description: string): JsonApiResponse<typeof errorDocumentSchema>;
+/**
+ * The `Retry-After` header object a refusal declares: whole seconds, sent on every answer it gives.
+ *
+ * A type alias, not an interface: `@hono/zod-openapi` types a header as openapi3-ts's `HeaderObject`,
+ * which carries an `x-${string}` index signature, and an interface is not assignable to one.
+ */
+export type RetryAfterHeader = {
+    description: string;
+    required: true;
+    schema: {
+        type: 'integer';
+        minimum: 1;
+    };
+};
+/**
+ * The response object for a failure status - the `errors[]` document.
+ *
+ * @param options.retryAfterSeconds - how long a refused caller is told to wait, in whole seconds.
+ *   Pass it only where the refusal always sets `Retry-After`, since the header is declared required.
+ * @throws {RangeError} when `retryAfterSeconds` is not a positive integer.
+ */
+export declare function errorResponse(description: string, options?: {
+    retryAfterSeconds: number;
+}): JsonApiResponse<typeof errorDocumentSchema>;
 /** The response object for a single resource, off the resource's own declaration. */
 export declare function okResponse<A extends ZodObject, C = unknown>(description: string, resource: JsonApiResource<A, C>): JsonApiResponse<ZodType<ResourceDocument<output<A>>>>;
 /** The response object for a collection, off the resource's own declaration. */

package/dist/api-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-response.d.ts","sourceRoot":"","sources":["../src/api-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,OAAO;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,OAAO,mBAAmB,EAAE;QAAE,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CAC5D;AAOD,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,mBAAmB,CAAC,CAE9F;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,GAAG,OAAO,EACzD,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC9B,eAAe,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAEvD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,GAAG,OAAO,EAC3D,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC9B,eAAe,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAEzD"}
+{"version":3,"file":"api-response.d.ts","sourceRoot":"","sources":["../src/api-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,OAAO;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,OAAO,mBAAmB,EAAE;QAAE,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IAC3D,OAAO,CAAC,EAAE;QAAE,aAAa,EAAE,gBAAgB,CAAA;KAAE,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,IAAI,CAAC;IACf,MAAM,EAAE;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,CAAC;CACzC,CAAC;AAOF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,iBAAiB,EAAE,MAAM,CAAA;CAAE,GACtC,eAAe,CAAC,OAAO,mBAAmB,CAAC,CAqB7C;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,GAAG,OAAO,EACzD,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC9B,eAAe,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAEvD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,GAAG,OAAO,EAC3D,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC9B,eAAe,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAEzD"}

package/dist/api-response.js

@@ -4,9 +4,32 @@ const answers = (description, schema) => ({
     description,
     content: { [JSON_API_MEDIA_TYPE]: { schema } },
 });
-/** The response object for a failure status - the `errors[]` document. */
-export function errorResponse(description) {
-    return answers(description, errorDocumentSchema);
+/**
+ * The response object for a failure status - the `errors[]` document.
+ *
+ * @param options.retryAfterSeconds - how long a refused caller is told to wait, in whole seconds.
+ *   Pass it only where the refusal always sets `Retry-After`, since the header is declared required.
+ * @throws {RangeError} when `retryAfterSeconds` is not a positive integer.
+ */
+export function errorResponse(description, options) {
+    const response = answers(description, errorDocumentSchema);
+    if (!options) {
+        return response;
+    }
+    const { retryAfterSeconds } = options;
+    if (!Number.isInteger(retryAfterSeconds) || retryAfterSeconds < 1) {
+        throw new RangeError(`retryAfterSeconds must be a positive integer, got ${retryAfterSeconds}`);
+    }
+    return {
+        ...response,
+        headers: {
+            'Retry-After': {
+                description: `Seconds to wait before calling again: ${retryAfterSeconds}`,
+                required: true,
+                schema: { type: 'integer', minimum: 1 },
+            },
+        },
+    };
 }
 /** The response object for a single resource, off the resource's own declaration. */
 export function okResponse(description, resource) {

package/dist/errors/error-registry.d.ts

@@ -37,6 +37,10 @@ export declare const BASE_ERROR_CODES: {
         readonly status: 422;
         readonly title: "Unprocessable Entity";
     };
+    readonly TOO_MANY_REQUESTS: {
+        readonly status: 429;
+        readonly title: "Too Many Requests";
+    };
     readonly INTERNAL_SERVER_ERROR: {
         readonly status: 500;
         readonly title: "Internal Server Error";

package/dist/errors/error-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-registry.d.ts","sourceRoot":"","sources":["../../src/errors/error-registry.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sHAAsH;AACtH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAWmB,CAAC"}
+{"version":3,"file":"error-registry.d.ts","sourceRoot":"","sources":["../../src/errors/error-registry.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sHAAsH;AACtH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAYmB,CAAC"}

package/dist/errors/error-registry.js

@@ -8,6 +8,7 @@ export const BASE_ERROR_CODES = {
     CONFLICT: { status: 409, title: 'Conflict' },
     UNSUPPORTED_MEDIA_TYPE: { status: 415, title: 'Unsupported Media Type' },
     UNPROCESSABLE_ENTITY: { status: 422, title: 'Unprocessable Entity' },
+    TOO_MANY_REQUESTS: { status: 429, title: 'Too Many Requests' },
     INTERNAL_SERVER_ERROR: { status: 500, title: 'Internal Server Error' },
     BAD_GATEWAY: { status: 502, title: 'Bad Gateway' },
 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * The response half of the HTTP contract, in the one wire spelling this house answers: a JSON:API document.
  */
-export { errorResponse, listResponse, okResponse, type JsonApiResponse } from './api-response.js';
+export { errorResponse, listResponse, okResponse, type JsonApiResponse, type RetryAfterHeader, } from './api-response.js';
 export type { CollectionDocument, Relationship, ResourceDocument, ResourceObject } from './document.js';
 export { declaredDocumentShape, type DeclaredDocumentShape } from './document-shape.js';
 export { createDomainErrorResolver, defineErrorMap, errorEntry, type DomainErrorAnswer, type DomainErrorEntry, } from './domain-error-resolver.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAClG,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACxG,OAAO,EAAE,qBAAqB,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrH,OAAO,EACL,MAAM,EACN,KAAK,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AACpH,OAAO,EAAE,6BAA6B,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACxG,OAAO,EAAE,qBAAqB,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrH,OAAO,EACL,MAAM,EACN,KAAK,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AACpH,OAAO,EAAE,6BAA6B,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 /**
  * The response half of the HTTP contract, in the one wire spelling this house answers: a JSON:API document.
  */
-export { errorResponse, listResponse, okResponse } from './api-response.js';
+export { errorResponse, listResponse, okResponse, } from './api-response.js';
 export { declaredDocumentShape } from './document-shape.js';
 export { createDomainErrorResolver, defineErrorMap, errorEntry, } from './domain-error-resolver.js';
 export { BASE_ERROR_CODES, errorDocumentSchema, JsonApiError, toErrorDocument, toErrorObject, } from './errors/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/response",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "private": false,
   "type": "module",
   "sideEffects": false,