@rdlabo/workers-hono-kit 0.6.11 → 0.6.14

package/README.md

@@ -2,15 +2,16 @@
 
 Infrastructure toolkit for building APIs on [Hono](https://hono.dev) + [Cloudflare Workers](https://workers.cloudflare.com).
 
-It provides the building blocks a NestJS-style API needs but that don't run on `workerd` (no Node.js AWS SDK, no `firebase-admin`), plus middleware that matches Express / NestJS response semantics byte-for-byte:
+It provides the building blocks a NestJS-style API needs but that don't run on `workerd` (no Node.js AWS SDK, no `firebase-admin`), plus middleware for common HTTP response concerns:
 
 - **Firebase ID-token verification** on Workers via [`jose`](https://github.com/panva/jose) (RS256 against Google's securetoken JWKS), with optional Identity Toolkit REST for `getUser` / `deleteUser`.
 - **AWS Secrets Manager / STS AssumeRole / CloudFront signed URLs** via SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) or Web Crypto — no AWS SDK.
-- **Middleware**: `finalizeResponse` (Express-compatible weak ETag + JSON charset), `validate` (NestJS `ValidationPipe`-shaped 400), and zod number-coercion helpers.
+- **Middleware**: `finalizeResponse` (weak ETag via `hono/etag`), `validate` (NestJS `ValidationPipe`-shaped 400), and zod number-coercion helpers.
 - **Standard API errors**: `createHttpErrorHandler` / `notFoundHandler` / `HttpStatus`.
 - **Deadlock retry** (`ER_LOCK_DEADLOCK` exponential backoff) and an optional **MySQL data layer** (`@rdlabo/workers-hono-kit/db`) for Hyperdrive + Drizzle.
 - **AI Gateway**: route `@ai-sdk` models through the Cloudflare AI Gateway.
 - **Stripe** Workers-native client + async webhook verification.
+- **Payment failure & subscription reconcile**: provider-agnostic `payment_failed` helpers — Stripe decline reasons → Japanese messages, Apple / Google subscription-renewal classification, `iapFailureKey` / receipt (de)serialization, and Stripe reconcile branch decisions.
 - **Testing helpers** (`@rdlabo/workers-hono-kit/testing`): a Drizzle-migration-backed test database, in-memory Firebase fake, configurable test doubles, and Stripe fixtures.
 
 ## Install
@@ -50,7 +51,7 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 
 | Export | Description |
 | --- | --- |
-| `finalizeResponse()` | Middleware that adds an Express-compatible weak `ETag` and JSON `charset=utf-8`. |
+| `finalizeResponse()` | Middleware that adds a weak `ETag` (delegates to `hono/etag`; also handles `If-None-Match` → `304`). |
 | `validate(target, schema, options?)` | Zod validator → NestJS `ValidationPipe`-shaped `400` (`{ statusCode, message[], error }`). `options.onValidationError(err, c)` to report (e.g. Sentry). |
 | `createValidate({ sentry? })` | Bound `validate` factory. Pass `sentry` on Sentry apps; omit for console-only (review, cbs-ai). |
 | `createSentryValidate(sentry)` | **Deprecated** — use `createValidate({ sentry })`. |
@@ -66,7 +67,7 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `getUserProtocol(c)` / `IUserProtocol` | Read client IP / UA (`CF-Connecting-IP` → `X-Forwarded-For`). |
 | `getAppInfo(c)` / `AppInfo` | Read `x-amz-meta-version` / `x-amz-meta-uuid`. |
 | `resolveAppEnv(env)` / `isProductionEnv(env)` / `AppEnv` | Resolve `'development'` / `'production'` from `env.APP_ENV` (defaults to `'production'` for safety). |
-| `HttpStatus` | HTTP status enum identical to NestJS `@nestjs/common`. |
+| `HttpStatus` | Standard HTTP status code enum (IANA registry). |
 | `createHttpErrorHandler(options?)` / `HttpErrorHandlerOptions` | `app.onError()` handler that maps a thrown `HTTPException` to `{ statusCode, message, error? }` (`401` omits `error`). Optional custom error predicate and unhandled-error report hook. Unhandled errors log via `console.error` (mysql2 errors include `sqlMessage` / `errno` when detectable). |
 | `createAppErrorHandler(options?)` / `CreateAppErrorHandlerOptions` | Standard `app.onError`: {@link createQueryFailedErrorHandler} + default {@link classifyGenericMysqlDriverError} + optional `sentry` (Sentry apps), `getReportError` / `reportError` (tests / container), or neither (no external reporting). |
 | `createQueryFailedErrorHandler(options)` / `QueryFailedClassifier` / `ClassifiedDbError` | Lower-level compose when you need full control over `classify` + `onUnhandledError` without defaults. |
@@ -77,12 +78,23 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `HTTP_ERROR_PHRASES` | `{ 400, 401, 403, 404 }` → standard `error` field phrases. |
 | `createAuthMiddleware(options)` / `AuthMiddlewareOptions` | Factory for a Firebase-token auth middleware: reads the token header, verifies, resolves the DB user id, and stashes the result on the context. Omit `resolveUserId` for a token-only (login) guard. |
 | `perfLog(options?)` / `PerfLogOptions` / `AnalyticsEngineDatasetLike` | Middleware that records one per-request latency data point (`t_app`, colo, cold/warm, route, status) and emits it to **Workers Logs** (`console.log`) and/or **Workers Analytics Engine** (`writeDataPoint`). Lets you measure low-traffic Workers without a live `wrangler tail`. |
+| `createMaintenanceMiddleware(options)` / `createMaintenanceWaitHandler(options)` / `isMaintenanceEnabled(env)` / `MAINTENANCE_CODE` / `MAINTENANCE_WAIT_PATH` | Fleet maintenance short-circuit: when enabled (`MAINTENANCE=1`), every non-allowlisted request returns `503` + `{ statusCode, message, code: 'MAINTENANCE' }` **before** container/DB. Pair with `GET /public/maintenance/wait` SSE (`event: ping` / `event: ended`) so clients can auto-dismiss a lock UI. Mount after `cors`, before `containerMiddleware`. |
 | `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createHttpErrorHandler`'s `onUnhandledError`. |
 | `createSentryErrorReporter(sentry)` / `SentryExceptionReporterLike` | Build an `ErrorReporter` that forwards to Sentry with an optional `request_id` tag (no hard `@sentry/cloudflare` dependency). |
 | `DeferExecutor` / `defaultDefer` / `createWaitUntilDefer(ctx)` | Fire-and-forget executor for Workers: `defaultDefer` swallows rejections (tests); `createWaitUntilDefer` registers work via `ctx.waitUntil`. |
 | `createAiGatewayProvider(config)` / `AiGatewayConfig` / `AiGatewayProvider` | Route `@ai-sdk` models through the Cloudflare AI Gateway, via either a Workers `AI` binding or REST credentials (`accountId` / `gateway` / `token`). |
 | `KVCache` / `KVNamespace` / `KVCacheOptions` | Workers-KV cache-aside helper (key `appName+version+table_type_column`, sha256 for string ids, TTL clamped ≥60s). Set `appName` / `version` per application. |
 | `createStripeClient(secret, opts?)` / `verifyStripeWebhook(...)` / `CreateStripeClientOptions` | Workers-native Stripe client (fetch transport) + async webhook verification (SubtleCrypto). `apiVersion` optional (pin to a fixed Stripe API version). |
+| `extractStripeFailureReason(source)` / `StripeFailureReason` | Duck-type a Stripe `PaymentIntent` / `Invoice` / `{ paymentIntent?, invoice? }` / thrown error into a normalized `{ code, declineCode, message, paymentIntentId, invoiceId, subscriptionId }` (SDK-free), or `null`. |
+| `stripeFailureMessageJa(reason)` | Render a `StripeFailureReason` (or `null`) as a single user-facing Japanese sentence (`decline_code` > `code`; fraud codes masked; unknown → generic). |
+| `PaymentDeclinedError` / `toPaymentDeclinedError(error, status?)` / `PaymentDeclinedBody` | `HTTPException` carrying a verbatim `{ statusCode, message, code?, declineCode? }` body for a synchronous card decline (defaults to `400`). `toPaymentDeclinedError` returns `null` for non-declines (re-throw → 500). |
+| `classifyStripeReconcile(subscription)` / `StripeReconcileAction` | Classify an expanded Stripe subscription into `trial` / `clear` / `canceled` / `failed` / `action_required` / `none` (termination evaluated before `succeeded`). Consumer does the DB write. |
+| `serializePaymentFailure(record)` / `parsePaymentFailure(receipt)` / `PaymentFailureRecord` / `PaymentFailureReason` / `PaymentFailureSource` | (De)serialize the `payment_failed.receipt` JSON. `parsePaymentFailure` restores both a full Stripe record and a bare IAP reason. |
+| `serializeIapFailureReason(reason)` / `IapFailureReason` | Serialize an IAP reason (`billing_retry` / `auto_renew_off` / `subscription_canceled` / `subscription_gone` + provider codes) directly, without the source/timestamp wrapper. |
+| `paymentFailureMessageJa(input)` / `PaymentFailureStatus` / `PaymentFailureType` / `UNRESOLVED_PAYMENT_STATUSES` | Provider-agnostic Japanese message for a `payment_failed` row (`canceled` re-subscribe prompt, IAP `failed` App Store/Google Play prompt, else Stripe wording). `UNRESOLVED_PAYMENT_STATUSES` = everything except `resolved` for read/resolve `WHERE`. |
+| `iapFailureKey(input)` | Provider-native `payment_failed.recursions_id`: iOS `${original_transaction_id}:${expires_date_ms}`, Android `${orderId}` (provider is in the `type` column). |
+| `verifyAppleReceipt(receipt, opts)` / `classifyAppleRenewal(verify, now)` / `AppleRenewalClassification` / `AppleRenewalState` / `AppleVerifyReceiptResponse` / `ApplePendingRenewalInfo` / `AppleLatestReceiptInfo` | Verify an App Store receipt (production → sandbox fallback; inject `password` / `fetchImpl`) and classify it into `billing_retry` / `lapsed` / `active` / `unknown` plus the raw fields used (`statusCode` / `billingRetryStatus` / `autoRenewStatus`, latest `original_transaction_id` / `expires_date_ms`). |
+| `googleAccessToken(creds, fetch?)` / `getGoogleSubscription(opts)` / `classifyGoogleSubscription(purchase, now)` / `GoogleSubscriptionClassification` / `GoogleSubscriptionState` / `GoogleSubscriptionPurchase` / `GoogleOAuthCredentials` | Exchange a refresh token for an Android Publisher access token (throws on `invalid_grant`), fetch a subscription purchase, and classify it into `canceled` / `gone` / `active` / `unknown` plus raw `statusCode` / `cancelReason`. |
 | `sendInChunks(queue, messages, options?)` / `QueueLike` / `QueueSendMessage` | Send queue messages in bounded chunks to stay under the Workers subrequest cap per invocation. `options.chunkSize` sets the per-batch size (defaults to and is capped at 100). |
 | `processBatch(batch, handler, options?)` / `MessageBatchLike` / `QueueMessageLike` / `ProcessBatchOptions` / `ProcessBatchResult` | Process a queue batch with bounded concurrency (consumer-side counterpart to `sendInChunks`). |
 | `createQueueErrorHandler(options)` / `CreateQueueErrorHandlerOptions` | Factory for `processBatch`'s `onError`: logs every failure; optional Sentry capture with queue/message context; optional `maxRetries` gate (report only on final attempt). |
@@ -195,7 +207,7 @@ Requires the `drizzle-orm` and `mysql2` peers. Consolidates duplicated test boil
 
 ## Usage
 
-### Response finalization (ETag / charset)
+### Response finalization (ETag)
 
 ```ts
 import { Hono } from 'hono';
@@ -504,6 +516,62 @@ const stripe = createStripeClient(secret); // or { apiVersion: '2024-04-10' } to
 const event = await verifyStripeWebhook(secret, webhookSecret, rawBody, c.req.header('stripe-signature') ?? '');
 ```
 
+### Payment failure & subscription reconcile
+
+Store only the raw reason; render the user-facing message on read (so wording changes never need a migration).
+
+```ts
+import {
+  extractStripeFailureReason,
+  serializePaymentFailure,
+  paymentFailureMessageJa,
+} from '@rdlabo/workers-hono-kit';
+
+// On a Stripe failure webhook: persist the normalized reason.
+const reason = extractStripeFailureReason(event.data.object);
+if (reason) {
+  await db.write.insert(paymentFailed).values({
+    type: 'stripe',
+    status: 'failed',
+    receipt: serializePaymentFailure({ reason, source: 'webhook.invoice.payment_failed', occurredAt }),
+  });
+}
+
+// On read: provider-agnostic Japanese message.
+const message = paymentFailureMessageJa({ status: row.status, type: row.type, reason: parsed?.reason });
+```
+
+In-app purchase: verify → classify → key the row by billing cycle.
+
+```ts
+import {
+  verifyAppleReceipt,
+  classifyAppleRenewal,
+  iapFailureKey,
+  serializeIapFailureReason,
+} from '@rdlabo/workers-hono-kit';
+
+const verify = await verifyAppleReceipt(receipt, { password: appleSharedSecret });
+const cls = classifyAppleRenewal(verify, Date.now());
+if (cls.state === 'billing_retry' || cls.state === 'lapsed') {
+  await db.write.insert(paymentFailed).values({
+    type: 'ios',
+    status: cls.state === 'billing_retry' ? 'failed' : 'canceled',
+    recursions_id: iapFailureKey({
+      platform: 'ios',
+      originalTransactionId: cls.originalTransactionId!,
+      expiresDateMs: cls.expiresDateMs!,
+    }),
+    receipt: serializeIapFailureReason({
+      code: cls.state === 'billing_retry' ? 'billing_retry' : 'subscription_canceled',
+      statusCode: cls.statusCode,
+      billingRetryStatus: cls.billingRetryStatus,
+      autoRenewStatus: cls.autoRenewStatus,
+    }),
+  });
+}
+```
+
 ### Testing
 
 ```ts

package/dist/http/http-status.d.ts

@@ -1,11 +1,11 @@
 /**
- * HTTP status codes mirroring the `HttpStatus` enum from `@nestjs/common`.
+ * Standard HTTP status codes, keyed by their conventional names.
  *
  * @remarks
- * Provides a single source of truth for referencing status codes by the same names NestJS uses, so a
- * Hono app can emit responses whose status matches a NestJS service byte-for-byte. The member set and
- * numeric values intentionally track `@nestjs/common` rather than the IANA registry, including a few
- * non-standard codes that NestJS ships.
+ * A single source of truth for referencing status codes by name from a Hono app. The member set and
+ * numeric values follow the IANA HTTP status code registry. (Earlier versions mirrored the
+ * `@nestjs/common` `HttpStatus` enum — including its non-standard codes and aliases — for a
+ * NestJS → Hono migration; that parity is no longer maintained.)
  */
 export declare enum HttpStatus {
     CONTINUE = 100,
@@ -21,10 +21,7 @@ export declare enum HttpStatus {
     PARTIAL_CONTENT = 206,
     MULTI_STATUS = 207,
     ALREADY_REPORTED = 208,
-    /** Non-standard WebDAV extension carried over from NestJS. */
-    CONTENT_DIFFERENT = 210,
-    /** Multiple Choices (300). Named `AMBIGUOUS` to match NestJS. */
-    AMBIGUOUS = 300,
+    MULTIPLE_CHOICES = 300,
     MOVED_PERMANENTLY = 301,
     FOUND = 302,
     SEE_OTHER = 303,
@@ -51,15 +48,12 @@ export declare enum HttpStatus {
     EXPECTATION_FAILED = 417,
     /** "I'm a teapot" (418), from RFC 2324. */
     I_AM_A_TEAPOT = 418,
-    /** Misdirected Request (421). Named `MISDIRECTED` to match NestJS. */
-    MISDIRECTED = 421,
+    MISDIRECTED_REQUEST = 421,
     UNPROCESSABLE_ENTITY = 422,
     LOCKED = 423,
     FAILED_DEPENDENCY = 424,
     PRECONDITION_REQUIRED = 428,
     TOO_MANY_REQUESTS = 429,
-    /** Non-standard code carried over from NestJS. */
-    UNRECOVERABLE_ERROR = 456,
     INTERNAL_SERVER_ERROR = 500,
     NOT_IMPLEMENTED = 501,
     BAD_GATEWAY = 502,

package/dist/http/http-status.js

@@ -1,11 +1,11 @@
 /**
- * HTTP status codes mirroring the `HttpStatus` enum from `@nestjs/common`.
+ * Standard HTTP status codes, keyed by their conventional names.
  *
  * @remarks
- * Provides a single source of truth for referencing status codes by the same names NestJS uses, so a
- * Hono app can emit responses whose status matches a NestJS service byte-for-byte. The member set and
- * numeric values intentionally track `@nestjs/common` rather than the IANA registry, including a few
- * non-standard codes that NestJS ships.
+ * A single source of truth for referencing status codes by name from a Hono app. The member set and
+ * numeric values follow the IANA HTTP status code registry. (Earlier versions mirrored the
+ * `@nestjs/common` `HttpStatus` enum — including its non-standard codes and aliases — for a
+ * NestJS → Hono migration; that parity is no longer maintained.)
  */
 export var HttpStatus;
 (function (HttpStatus) {
@@ -22,10 +22,7 @@ export var HttpStatus;
     HttpStatus[HttpStatus["PARTIAL_CONTENT"] = 206] = "PARTIAL_CONTENT";
     HttpStatus[HttpStatus["MULTI_STATUS"] = 207] = "MULTI_STATUS";
     HttpStatus[HttpStatus["ALREADY_REPORTED"] = 208] = "ALREADY_REPORTED";
-    /** Non-standard WebDAV extension carried over from NestJS. */
-    HttpStatus[HttpStatus["CONTENT_DIFFERENT"] = 210] = "CONTENT_DIFFERENT";
-    /** Multiple Choices (300). Named `AMBIGUOUS` to match NestJS. */
-    HttpStatus[HttpStatus["AMBIGUOUS"] = 300] = "AMBIGUOUS";
+    HttpStatus[HttpStatus["MULTIPLE_CHOICES"] = 300] = "MULTIPLE_CHOICES";
     HttpStatus[HttpStatus["MOVED_PERMANENTLY"] = 301] = "MOVED_PERMANENTLY";
     HttpStatus[HttpStatus["FOUND"] = 302] = "FOUND";
     HttpStatus[HttpStatus["SEE_OTHER"] = 303] = "SEE_OTHER";
@@ -52,15 +49,12 @@ export var HttpStatus;
     HttpStatus[HttpStatus["EXPECTATION_FAILED"] = 417] = "EXPECTATION_FAILED";
     /** "I'm a teapot" (418), from RFC 2324. */
     HttpStatus[HttpStatus["I_AM_A_TEAPOT"] = 418] = "I_AM_A_TEAPOT";
-    /** Misdirected Request (421). Named `MISDIRECTED` to match NestJS. */
-    HttpStatus[HttpStatus["MISDIRECTED"] = 421] = "MISDIRECTED";
+    HttpStatus[HttpStatus["MISDIRECTED_REQUEST"] = 421] = "MISDIRECTED_REQUEST";
     HttpStatus[HttpStatus["UNPROCESSABLE_ENTITY"] = 422] = "UNPROCESSABLE_ENTITY";
     HttpStatus[HttpStatus["LOCKED"] = 423] = "LOCKED";
     HttpStatus[HttpStatus["FAILED_DEPENDENCY"] = 424] = "FAILED_DEPENDENCY";
     HttpStatus[HttpStatus["PRECONDITION_REQUIRED"] = 428] = "PRECONDITION_REQUIRED";
     HttpStatus[HttpStatus["TOO_MANY_REQUESTS"] = 429] = "TOO_MANY_REQUESTS";
-    /** Non-standard code carried over from NestJS. */
-    HttpStatus[HttpStatus["UNRECOVERABLE_ERROR"] = 456] = "UNRECOVERABLE_ERROR";
     HttpStatus[HttpStatus["INTERNAL_SERVER_ERROR"] = 500] = "INTERNAL_SERVER_ERROR";
     HttpStatus[HttpStatus["NOT_IMPLEMENTED"] = 501] = "NOT_IMPLEMENTED";
     HttpStatus[HttpStatus["BAD_GATEWAY"] = 502] = "BAD_GATEWAY";

package/dist/index.d.ts

@@ -18,6 +18,8 @@ export { createAuthMiddleware } from './middleware/auth.js';
 export type { AuthMiddlewareOptions } from './middleware/auth.js';
 export { perfLog } from './middleware/perf-log.js';
 export type { PerfLogOptions, AnalyticsEngineDatasetLike } from './middleware/perf-log.js';
+export { createMaintenanceMiddleware, createMaintenanceWaitHandler, isMaintenanceEnabled, MAINTENANCE_BODY, MAINTENANCE_CODE, MAINTENANCE_WAIT_PATH, } from './middleware/maintenance.js';
+export type { MaintenanceBody, MaintenanceMiddlewareOptions, MaintenanceWaitOptions, } from './middleware/maintenance.js';
 export { createIsolateMemo } from './container/isolate-memo.js';
 export type { IsolateMemo } from './container/isolate-memo.js';
 export { createContainerRuntime } from './container/middleware.js';

package/dist/index.js

@@ -18,6 +18,7 @@ export { createSentryValidate } from './middleware/validation.js';
 export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce.js';
 export { createAuthMiddleware } from './middleware/auth.js';
 export { perfLog } from './middleware/perf-log.js';
+export { createMaintenanceMiddleware, createMaintenanceWaitHandler, isMaintenanceEnabled, MAINTENANCE_BODY, MAINTENANCE_CODE, MAINTENANCE_WAIT_PATH, } from './middleware/maintenance.js';
 export { createIsolateMemo } from './container/isolate-memo.js';
 export { createContainerRuntime } from './container/middleware.js';
 // http

package/dist/middleware/finalize-response.d.ts

@@ -1,21 +1,21 @@
 import type { MiddlewareHandler } from 'hono';
 /**
- * Create a Hono middleware that finalizes responses for byte-parity with an Express/Nest backend.
+ * Create a Hono middleware that adds a weak ETag to buffered responses.
  *
- * After the downstream handler runs, it performs two adjustments:
+ * @remarks
+ * ETag generation (and conditional `If-None-Match` → `304 Not Modified` handling) is delegated to
+ * Hono's official `hono/etag` middleware in weak mode, so the ETag format is `W/"<sha1-hex>"`. This
+ * no longer emulates the Express `etag` package byte-for-byte — the kit dropped NestJS/Express parity.
  *
- * 1. **JSON charset**: Express's `res.json` emits `application/json; charset=utf-8`, whereas Hono's
- *    `c.json` emits a bare `application/json`. A bare `application/json` content type is rewritten
- *    to include `; charset=utf-8`.
- * 2. **Weak ETag**: An Express `etag`-package compatible weak ETag is added, matching the format an
- *    Express/Nest backend applies to responses by default. See {@link weakEtag} for the exact format.
+ * Two categories of response are skipped so the downstream stream is never consumed:
  *
- * Server-Sent Events (`text/event-stream`) are skipped entirely because the stream cannot be
- * buffered. ETag generation is also skipped for `204`/`304` responses, responses that already carry
- * an `etag` header, and responses without a body.
+ * 1. **Server-Sent Events** (`text/event-stream`): the stream cannot be buffered to hash.
+ * 2. **Bodyless responses** (e.g. `204`/`304`, or handlers returning `null`): nothing to hash.
  *
- * @returns A {@link MiddlewareHandler} that rewrites the response headers (and body, when an ETag
- * must be computed) in place.
+ * Responses that already carry an `ETag` header are left untouched by `hono/etag`.
+ *
+ * @returns A {@link MiddlewareHandler} that sets the `ETag` header (or short-circuits to `304` when
+ * the request's `If-None-Match` matches).
  *
  * @example
  * ```ts
@@ -25,8 +25,7 @@ import type { MiddlewareHandler } from 'hono';
  * const app = new Hono();
  * app.use('*', finalizeResponse());
  * app.get('/users', (c) => c.json({ ok: true }));
- * // → Content-Type: application/json; charset=utf-8
- * // → ETag: W/"b-..." (b = 0xb = 11 bytes, the length of `{"ok":true}`)
+ * // → ETag: W/"<sha1-hex of the body>"
  * ```
  */
 export declare function finalizeResponse(): MiddlewareHandler;

package/dist/middleware/finalize-response.js

@@ -1,41 +1,29 @@
+import { etag } from 'hono/etag';
 /**
- * Compute an Express `etag`-package compatible weak ETag for a response body.
+ * Pre-built Hono ETag middleware in weak mode.
  *
- * The format is `W/"<byteLength-in-hex>-<first 27 chars of base64(sha1(body))>"`, byte-for-byte
- * identical to the weak ETag produced by the Express `etag` package. This deliberately differs
- * from `hono/etag`'s own format so responses match an Express/Nest backend exactly.
- *
- * @param body - The raw response body bytes to hash.
- * @returns The weak ETag header value (e.g. `W/"1a-Qwerty..."`).
+ * @remarks
+ * Reused across requests; it is stateless per invocation (all state lives on the passed `Context`).
  * @internal
  */
-async function weakEtag(body) {
-    const digest = await crypto.subtle.digest('SHA-1', body);
-    const bytes = new Uint8Array(digest);
-    let bin = '';
-    for (const b of bytes) {
-        bin += String.fromCharCode(b);
-    }
-    const b64 = btoa(bin).substring(0, 27);
-    return `W/"${body.byteLength.toString(16)}-${b64}"`;
-}
+const applyWeakEtag = etag({ weak: true });
 /**
- * Create a Hono middleware that finalizes responses for byte-parity with an Express/Nest backend.
+ * Create a Hono middleware that adds a weak ETag to buffered responses.
  *
- * After the downstream handler runs, it performs two adjustments:
+ * @remarks
+ * ETag generation (and conditional `If-None-Match` → `304 Not Modified` handling) is delegated to
+ * Hono's official `hono/etag` middleware in weak mode, so the ETag format is `W/"<sha1-hex>"`. This
+ * no longer emulates the Express `etag` package byte-for-byte — the kit dropped NestJS/Express parity.
  *
- * 1. **JSON charset**: Express's `res.json` emits `application/json; charset=utf-8`, whereas Hono's
- *    `c.json` emits a bare `application/json`. A bare `application/json` content type is rewritten
- *    to include `; charset=utf-8`.
- * 2. **Weak ETag**: An Express `etag`-package compatible weak ETag is added, matching the format an
- *    Express/Nest backend applies to responses by default. See {@link weakEtag} for the exact format.
+ * Two categories of response are skipped so the downstream stream is never consumed:
  *
- * Server-Sent Events (`text/event-stream`) are skipped entirely because the stream cannot be
- * buffered. ETag generation is also skipped for `204`/`304` responses, responses that already carry
- * an `etag` header, and responses without a body.
+ * 1. **Server-Sent Events** (`text/event-stream`): the stream cannot be buffered to hash.
+ * 2. **Bodyless responses** (e.g. `204`/`304`, or handlers returning `null`): nothing to hash.
  *
- * @returns A {@link MiddlewareHandler} that rewrites the response headers (and body, when an ETag
- * must be computed) in place.
+ * Responses that already carry an `ETag` header are left untouched by `hono/etag`.
+ *
+ * @returns A {@link MiddlewareHandler} that sets the `ETag` header (or short-circuits to `304` when
+ * the request's `If-None-Match` matches).
  *
  * @example
  * ```ts
@@ -45,38 +33,19 @@ async function weakEtag(body) {
  * const app = new Hono();
  * app.use('*', finalizeResponse());
  * app.get('/users', (c) => c.json({ ok: true }));
- * // → Content-Type: application/json; charset=utf-8
- * // → ETag: W/"b-..." (b = 0xb = 11 bytes, the length of `{"ok":true}`)
+ * // → ETag: W/"<sha1-hex of the body>"
  * ```
  */
 export function finalizeResponse() {
     return async (c, next) => {
         await next();
-        const status = c.res.status;
         const contentType = c.res.headers.get('content-type') ?? '';
-        // Leave SSE / streaming responses untouched.
-        if (contentType.includes('text/event-stream')) {
-            return;
-        }
-        // Charset target: add the charset when a JSON response leaves it unspecified.
-        const needsCharset = contentType === 'application/json';
-        // ETag target: Express omits it on 204/304 and respects an existing ETag.
-        const needsEtag = status !== 204 && status !== 304 && !c.res.headers.has('etag') && !!c.res.body;
-        if (!needsCharset && !needsEtag) {
+        // Leave SSE / streaming responses untouched, and skip bodyless responses (204/304/null).
+        if (contentType.includes('text/event-stream') || !c.res.body) {
             return;
         }
-        const headers = new Headers(c.res.headers);
-        if (needsCharset) {
-            headers.set('content-type', 'application/json; charset=utf-8');
-        }
-        if (needsEtag) {
-            const buf = await c.res.clone().arrayBuffer();
-            headers.set('ETag', await weakEtag(buf));
-            c.res = new Response(buf, { status, statusText: c.res.statusText, headers });
-        }
-        else {
-            // Swap only the headers without reading the body.
-            c.res = new Response(c.res.body, { status, statusText: c.res.statusText, headers });
-        }
+        // The downstream handler already ran, so pass a no-op `next`; `hono/etag` then hashes the
+        // buffered body and applies the ETag (or a conditional 304) to the existing response.
+        await applyWeakEtag(c, async () => undefined);
     };
 }

package/dist/middleware/maintenance.d.ts

@@ -0,0 +1,113 @@
+import type { Context, Env, MiddlewareHandler } from 'hono';
+/** Canonical API error `code` for fleet-wide maintenance short-circuit. */
+export declare const MAINTENANCE_CODE: "MAINTENANCE";
+/** Default allowlisted SSE path that stays open while the rest of the API returns 503. */
+export declare const MAINTENANCE_WAIT_PATH = "/public/maintenance/wait";
+/** JSON body returned for every blocked request during maintenance. */
+export interface MaintenanceBody {
+    statusCode: 503;
+    message: string;
+    code: typeof MAINTENANCE_CODE;
+}
+/** Default 503 body (no phrase `error` field — would collide with `code` shape on the client). */
+export declare const MAINTENANCE_BODY: MaintenanceBody;
+/**
+ * True when the Workers binding / wrangler var `MAINTENANCE` is the string `'1'`.
+ *
+ * @param env - Bindings object that may carry `MAINTENANCE`
+ */
+export declare function isMaintenanceEnabled(env: {
+    MAINTENANCE?: string;
+} | null | undefined): boolean;
+/**
+ * Options for {@link createMaintenanceMiddleware}.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ */
+export interface MaintenanceMiddlewareOptions<E extends Env = Env> {
+    /**
+     * Whether maintenance mode is currently on for this request.
+     *
+     * @remarks
+     * Typical wiring: `(c) => isMaintenanceEnabled(c.env)`. Injected so tests and non-env sources
+     * (future KV) can supply their own predicate without forking the middleware.
+     */
+    isEnabled: (c: Context<E>) => boolean;
+    /**
+     * Paths that stay reachable during maintenance (default: {@link MAINTENANCE_WAIT_PATH}).
+     *
+     * @remarks
+     * Compared against `pathname` with and without a trailing slash. {@link MAINTENANCE_WAIT_PATH}
+     * is handled inside this middleware (SSE) so it never reaches container/DB. Other allowlisted
+     * paths call `next()`.
+     */
+    allowPaths?: readonly string[];
+    /** Override the default {@link MAINTENANCE_BODY.message}. */
+    message?: string;
+    /** Optional `Retry-After` header (seconds). */
+    retryAfterSeconds?: number;
+    /**
+     * Ping interval for the in-middleware wait SSE (ms). Defaults to `5_000`.
+     *
+     * @see {@link MaintenanceWaitOptions.pingIntervalMs}
+     */
+    pingIntervalMs?: number;
+}
+/**
+ * Options for {@link createMaintenanceWaitHandler}.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ */
+export interface MaintenanceWaitOptions<E extends Env = Env> {
+    /**
+     * Whether maintenance mode is still on. Re-evaluated on each ping tick.
+     *
+     * @remarks
+     * Wrangler `vars` do not change inside a long-lived isolate; after a deploy that clears
+     * `MAINTENANCE`, new connections (and clients that reconnect) see `false` and get `ended`.
+     */
+    isEnabled: (c: Context<E>) => boolean;
+    /**
+     * Interval between SSE `ping` events and `isEnabled` re-checks (ms). Defaults to `5_000`.
+     */
+    pingIntervalMs?: number;
+}
+/**
+ * Short-circuit middleware: when enabled, every non-allowlisted request returns
+ * `503` + `{ statusCode, message, code: 'MAINTENANCE' }` without running downstream
+ * (so container / Hyperdrive / secrets stay cold).
+ *
+ * @remarks
+ * Mount **after** `cors` / `finalizeResponse` and **before** `containerMiddleware`.
+ * {@link MAINTENANCE_WAIT_PATH} is served **inside this middleware** (both when
+ * maintenance is on and off) so the wait SSE never reaches container / DB. Other
+ * `allowPaths` still call `next()`.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ * @param options - Enable predicate, allowlist, and optional body/header overrides.
+ * @returns A {@link MiddlewareHandler} that either returns 503 / SSE or calls `next()`.
+ *
+ * @example
+ * ```ts
+ * app.use('*', createMaintenanceMiddleware({
+ *   isEnabled: (c) => isMaintenanceEnabled(c.env),
+ * }));
+ * // Optional: also register createMaintenanceWaitHandler as a route — redundant when
+ * // this middleware is mounted, because MAINTENANCE_WAIT_PATH is handled here.
+ * ```
+ */
+export declare function createMaintenanceMiddleware<E extends Env = Env>(options: MaintenanceMiddlewareOptions<E>): MiddlewareHandler<E>;
+/**
+ * SSE handler for {@link MAINTENANCE_WAIT_PATH}.
+ *
+ * @remarks
+ * - Already off → emit `event: ended` once and close.
+ * - Still on → emit `event: ping` on an interval; when `isEnabled` becomes false, emit
+ *   `event: ended` and close. Clients should close the EventSource on `ended` and dismiss UI.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ * @param options - Enable predicate and ping interval.
+ * @returns A handler `(c) => Response` suitable for `app.get(MAINTENANCE_WAIT_PATH, …)`
+ *   or for embedding inside {@link createMaintenanceMiddleware}.
+ */
+export declare function createMaintenanceWaitHandler<E extends Env = Env>(options: MaintenanceWaitOptions<E>): (c: Context<E>) => Response;

package/dist/middleware/maintenance.js

@@ -0,0 +1,171 @@
+/** Canonical API error `code` for fleet-wide maintenance short-circuit. */
+export const MAINTENANCE_CODE = 'MAINTENANCE';
+/** Default allowlisted SSE path that stays open while the rest of the API returns 503. */
+export const MAINTENANCE_WAIT_PATH = '/public/maintenance/wait';
+/** Default 503 body (no phrase `error` field — would collide with `code` shape on the client). */
+export const MAINTENANCE_BODY = {
+    statusCode: 503,
+    message: 'Service temporarily unavailable',
+    code: MAINTENANCE_CODE,
+};
+/**
+ * True when the Workers binding / wrangler var `MAINTENANCE` is the string `'1'`.
+ *
+ * @param env - Bindings object that may carry `MAINTENANCE`
+ */
+export function isMaintenanceEnabled(env) {
+    return env?.MAINTENANCE === '1';
+}
+const SSE_HEADERS = {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+    'X-Accel-Buffering': 'no',
+};
+function normalizePath(pathname) {
+    if (pathname.length > 1 && pathname.endsWith('/')) {
+        return pathname.slice(0, -1);
+    }
+    return pathname;
+}
+function isAllowlisted(pathname, allowPaths) {
+    const normalized = normalizePath(pathname);
+    return allowPaths.has(normalized) || allowPaths.has(pathname);
+}
+/**
+ * Short-circuit middleware: when enabled, every non-allowlisted request returns
+ * `503` + `{ statusCode, message, code: 'MAINTENANCE' }` without running downstream
+ * (so container / Hyperdrive / secrets stay cold).
+ *
+ * @remarks
+ * Mount **after** `cors` / `finalizeResponse` and **before** `containerMiddleware`.
+ * {@link MAINTENANCE_WAIT_PATH} is served **inside this middleware** (both when
+ * maintenance is on and off) so the wait SSE never reaches container / DB. Other
+ * `allowPaths` still call `next()`.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ * @param options - Enable predicate, allowlist, and optional body/header overrides.
+ * @returns A {@link MiddlewareHandler} that either returns 503 / SSE or calls `next()`.
+ *
+ * @example
+ * ```ts
+ * app.use('*', createMaintenanceMiddleware({
+ *   isEnabled: (c) => isMaintenanceEnabled(c.env),
+ * }));
+ * // Optional: also register createMaintenanceWaitHandler as a route — redundant when
+ * // this middleware is mounted, because MAINTENANCE_WAIT_PATH is handled here.
+ * ```
+ */
+export function createMaintenanceMiddleware(options) {
+    const allowPaths = new Set((options.allowPaths ?? [MAINTENANCE_WAIT_PATH]).map((p) => normalizePath(p)));
+    const message = options.message ?? MAINTENANCE_BODY.message;
+    const waitHandler = createMaintenanceWaitHandler({
+        isEnabled: options.isEnabled,
+        pingIntervalMs: options.pingIntervalMs,
+    });
+    const waitPath = normalizePath(MAINTENANCE_WAIT_PATH);
+    return async (c, next) => {
+        const pathname = normalizePath(new URL(c.req.url).pathname);
+        // Wait SSE must never hit container/DB — handle it here whether maintenance is on or off.
+        if (pathname === waitPath) {
+            return waitHandler(c);
+        }
+        if (!options.isEnabled(c)) {
+            return next();
+        }
+        if (isAllowlisted(pathname, allowPaths)) {
+            return next();
+        }
+        if (options.retryAfterSeconds != null) {
+            c.header('Retry-After', String(options.retryAfterSeconds));
+        }
+        const body = {
+            statusCode: 503,
+            message,
+            code: MAINTENANCE_CODE,
+        };
+        return c.json(body, 503);
+    };
+}
+/**
+ * SSE handler for {@link MAINTENANCE_WAIT_PATH}.
+ *
+ * @remarks
+ * - Already off → emit `event: ended` once and close.
+ * - Still on → emit `event: ping` on an interval; when `isEnabled` becomes false, emit
+ *   `event: ended` and close. Clients should close the EventSource on `ended` and dismiss UI.
+ *
+ * @typeParam E - The Hono `Env` of the application.
+ * @param options - Enable predicate and ping interval.
+ * @returns A handler `(c) => Response` suitable for `app.get(MAINTENANCE_WAIT_PATH, …)`
+ *   or for embedding inside {@link createMaintenanceMiddleware}.
+ */
+export function createMaintenanceWaitHandler(options) {
+    const pingIntervalMs = options.pingIntervalMs ?? 5_000;
+    const encoder = new TextEncoder();
+    return (c) => {
+        const clientSignal = c.req.raw.signal;
+        if (!options.isEnabled(c)) {
+            const stream = new ReadableStream({
+                start(controller) {
+                    controller.enqueue(encoder.encode('event: ended\ndata: ended\n\n'));
+                    controller.close();
+                },
+            });
+            return new Response(stream, { headers: SSE_HEADERS });
+        }
+        let heartbeat;
+        const stream = new ReadableStream({
+            start(controller) {
+                let closed = false;
+                const close = () => {
+                    if (closed) {
+                        return;
+                    }
+                    closed = true;
+                    if (heartbeat) {
+                        clearInterval(heartbeat);
+                        heartbeat = undefined;
+                    }
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        /* already closed */
+                    }
+                };
+                const enqueue = (chunk) => {
+                    try {
+                        controller.enqueue(encoder.encode(chunk));
+                    }
+                    catch {
+                        close();
+                    }
+                };
+                const end = () => {
+                    enqueue('event: ended\ndata: ended\n\n');
+                    close();
+                };
+                if (clientSignal.aborted) {
+                    close();
+                    return;
+                }
+                clientSignal.addEventListener('abort', close, { once: true });
+                heartbeat = setInterval(() => {
+                    if (!options.isEnabled(c)) {
+                        end();
+                        return;
+                    }
+                    enqueue('event: ping\ndata: ping\n\n');
+                }, pingIntervalMs);
+            },
+            cancel() {
+                if (heartbeat) {
+                    clearInterval(heartbeat);
+                    heartbeat = undefined;
+                }
+            },
+        });
+        return new Response(stream, { headers: SSE_HEADERS });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.6.11",
+  "version": "0.6.14",
   "private": false,
   "publishConfig": {
     "access": "public"

package/dist/http/nest-error.d.ts

@@ -1,149 +0,0 @@
-import type { Context, Env } from 'hono';
-import type { ContentfulStatusCode } from 'hono/utils/http-status';
-/**
- * Reason phrases attached by the NestJS default exception filter, keyed by HTTP status code.
- *
- * @remarks
- * Mirrors the `error` field values NestJS produces for common client-error statuses, so a Hono app can
- * return byte-identical error bodies. Used as the default `reasonPhrases` map by {@link createNestErrorHandler}.
- */
-export declare const NEST_REASON_PHRASES: Record<number, string>;
-/**
- * Contextual metadata passed to an {@link ErrorReporter} when reporting an unexpected error.
- */
-export interface ErrorReportContext {
-    /** Correlation id for the failing request, if one is tracked. */
-    requestId?: string;
-}
-/**
- * Signature of a function that reports an unexpected (non-HTTP) error to an external sink such as Sentry.
- *
- * @remarks
- * Wire it into {@link createNestErrorHandler} via `onUnhandledError`, e.g.
- * `(err, c) => reporter(err, { requestId: c.get('requestId') })`. The reporting client itself is
- * intentionally kept out of this kit; the consumer supplies the implementation.
- *
- * @param error - The thrown value being reported.
- * @param context - Optional correlation context for the failing request.
- */
-export type ErrorReporter = (error: unknown, context?: ErrorReportContext) => void;
-/**
- * Minimal Sentry-like client for {@link createSentryErrorReporter} and {@link createQueueErrorHandler}.
- *
- * @remarks
- * Declared structurally to avoid a hard dependency on `@sentry/cloudflare`.
- */
-export interface SentryExceptionReporterLike {
-    captureException(exception: unknown, captureContext?: {
-        tags?: Record<string, string>;
-        extra?: Record<string, unknown>;
-    }): void;
-}
-/**
- * Build an {@link ErrorReporter} that forwards unhandled errors to Sentry with an optional `request_id` tag.
- */
-export declare function createSentryErrorReporter(sentry: SentryExceptionReporterLike): ErrorReporter;
-/**
- * Minimal shape read from a value treated as an HTTP error: its status, message, and optional body.
- *
- * @internal
- */
-interface HttpErrorLike {
-    /** HTTP status code to respond with. */
-    status: ContentfulStatusCode;
-    /** Human-readable error message placed in the response body. */
-    message: string;
-    /**
-     * Escape hatch for a fully custom response body. When present, it is rendered verbatim instead of
-     * the NestJS-shaped body.
-     */
-    body?: unknown;
-}
-/**
- * Options controlling how {@link createNestErrorHandler} shapes error responses.
- *
- * @typeParam E - The Hono environment type, so `onUnhandledError` receives a correctly typed context.
- */
-export interface NestErrorHandlerOptions<E extends Env = Env> {
-    /** Status-to-reason-phrase map for the `error` field. Defaults to {@link NEST_REASON_PHRASES}. */
-    reasonPhrases?: Record<number, string>;
-    /**
-     * Statuses that return only `{ statusCode, message }`, omitting the `error` field. Defaults to `[401]`,
-     * matching NestJS where a generic `HttpException(msg, 401)` carries no `error`.
-     */
-    bareStatuses?: readonly number[];
-    /**
-     * Field order of the non-bare error body. Defaults to `'statusCode-first'` (the NestJS canonical order).
-     * Use `'message-first'` to emit `{ message, error, statusCode }` when byte parity requires it.
-     */
-    fieldOrder?: 'statusCode-first' | 'message-first';
-    /**
-     * Fallback `error` value for statuses that are neither bare nor present in `reasonPhrases`. Defaults to
-     * `undefined`, meaning the `error` field is omitted when no reason phrase is known. Set to a string such
-     * as `'Error'` to always include an `error` field, faithfully reproducing the NestJS default exception
-     * filter behavior where `error` is always present.
-     */
-    fallbackReason?: string;
-    /**
-     * Predicate identifying which thrown values are HTTP errors. Defaults to detecting Hono's `HTTPException`.
-     * Override it (e.g. `(e) => e instanceof MyHttpError`) when the app throws a custom HTTP error type.
-     */
-    isHttpError?: (err: unknown) => err is HttpErrorLike;
-    /**
-     * Hook invoked before an unexpected (non-HTTP) error is returned as a 500, typically used to report the
-     * error (e.g. to Sentry). Any exception thrown by this hook is swallowed so reporting cannot alter the
-     * error response.
-     */
-    onUnhandledError?: (err: unknown, c: Context<E>) => void;
-    /**
-     * Response body for unexpected errors returned as 500. Defaults to
-     * `{ statusCode: 500, message: 'Internal server error' }`.
-     */
-    internalServerErrorBody?: unknown;
-}
-/**
- * Create a Hono `onError` handler that maps thrown errors to NestJS-shaped error JSON.
- *
- * @remarks
- * Reproduces the NestJS default exception filter so a Hono app returns byte-identical error bodies:
- * - HTTP errors (by default `HTTPException`) are mapped to a NestJS-shaped body; if the error carries a
- *   custom `body`, that body is returned verbatim.
- * - Statuses listed in `bareStatuses` (default `[401]`) omit the `error` field.
- * - Any other (unexpected) error triggers `onUnhandledError`, is logged via `console.error`, and returns 500.
- *
- * Per-app differences in body field order, HTTP error type, and reporting hook are absorbed through
- * {@link NestErrorHandlerOptions}, while the branching logic stays shared.
- *
- * @typeParam E - The Hono environment type propagated to `onUnhandledError`.
- * @param options - Overrides for reason phrases, bare statuses, field order, error detection, and reporting.
- * @returns A handler suitable for `app.onError(...)`.
- *
- * @example
- * ```ts
- * app.onError(
- *   createNestErrorHandler({
- *     fieldOrder: 'message-first',
- *     fallbackReason: 'Error',
- *     onUnhandledError: (err, c) => reportError(err, { requestId: c.get('requestId') }),
- *   }),
- * );
- * ```
- */
-export declare function createNestErrorHandler<E extends Env = Env>(options?: NestErrorHandlerOptions<E>): (err: Error, c: Context<E>) => Response;
-/**
- * Hono `notFound` handler that returns the canonical Express/NestJS unmatched-route 404 body.
- *
- * @remarks
- * Produces `{ message: "Cannot <METHOD> <path>", error: 'Not Found', statusCode: 404 }`, matching the
- * NestJS default 404 response so unmatched routes stay byte-identical.
- *
- * @param c - The Hono request context for the unmatched route.
- * @returns A 404 JSON response.
- *
- * @example
- * ```ts
- * app.notFound(nestNotFoundHandler);
- * ```
- */
-export declare function nestNotFoundHandler(c: Context): Response;
-export {};

package/dist/http/nest-error.js

@@ -1,120 +0,0 @@
-import { findMysqlDriverError, logMysqlDriverError } from './mysql-driver-error.js';
-/**
- * Reason phrases attached by the NestJS default exception filter, keyed by HTTP status code.
- *
- * @remarks
- * Mirrors the `error` field values NestJS produces for common client-error statuses, so a Hono app can
- * return byte-identical error bodies. Used as the default `reasonPhrases` map by {@link createNestErrorHandler}.
- */
-export const NEST_REASON_PHRASES = {
-    400: 'Bad Request',
-    401: 'Unauthorized',
-    403: 'Forbidden',
-    404: 'Not Found',
-};
-/**
- * Build an {@link ErrorReporter} that forwards unhandled errors to Sentry with an optional `request_id` tag.
- */
-export function createSentryErrorReporter(sentry) {
-    return (error, context) => {
-        sentry.captureException(error, context?.requestId ? { tags: { request_id: context.requestId } } : undefined);
-    };
-}
-/**
- * Structurally detect Hono's `HTTPException` without relying on `instanceof`.
- *
- * @remarks
- * When this kit is symlinked into a consumer, the `hono` instance it resolves can differ from the
- * consumer's `hono`, so an `HTTPException` from one copy fails an `instanceof` check against the other.
- * Detecting the presence of a `getResponse()` method and a numeric `status` is stable across module
- * boundaries and production bundles.
- *
- * @param err - The thrown value to test.
- * @returns `true` when `err` looks like a Hono `HTTPException`.
- *
- * @internal
- */
-const isHTTPException = (err) => err instanceof Error &&
-    typeof err.getResponse === 'function' &&
-    typeof err.status === 'number';
-/**
- * Create a Hono `onError` handler that maps thrown errors to NestJS-shaped error JSON.
- *
- * @remarks
- * Reproduces the NestJS default exception filter so a Hono app returns byte-identical error bodies:
- * - HTTP errors (by default `HTTPException`) are mapped to a NestJS-shaped body; if the error carries a
- *   custom `body`, that body is returned verbatim.
- * - Statuses listed in `bareStatuses` (default `[401]`) omit the `error` field.
- * - Any other (unexpected) error triggers `onUnhandledError`, is logged via `console.error`, and returns 500.
- *
- * Per-app differences in body field order, HTTP error type, and reporting hook are absorbed through
- * {@link NestErrorHandlerOptions}, while the branching logic stays shared.
- *
- * @typeParam E - The Hono environment type propagated to `onUnhandledError`.
- * @param options - Overrides for reason phrases, bare statuses, field order, error detection, and reporting.
- * @returns A handler suitable for `app.onError(...)`.
- *
- * @example
- * ```ts
- * app.onError(
- *   createNestErrorHandler({
- *     fieldOrder: 'message-first',
- *     fallbackReason: 'Error',
- *     onUnhandledError: (err, c) => reportError(err, { requestId: c.get('requestId') }),
- *   }),
- * );
- * ```
- */
-export function createNestErrorHandler(options = {}) {
-    const { reasonPhrases = NEST_REASON_PHRASES, bareStatuses = [401], fieldOrder = 'statusCode-first', isHttpError = isHTTPException, onUnhandledError, internalServerErrorBody = { statusCode: 500, message: 'Internal server error' }, fallbackReason, } = options;
-    return (err, c) => {
-        if (isHttpError(err)) {
-            // Escape hatch for a custom error body: render it verbatim.
-            if (err.body !== undefined) {
-                return c.json(err.body, err.status);
-            }
-            // reasonPhrases[status] is typed as string, but with noUncheckedIndexedAccess disabled it can be
-            // undefined at runtime. The fallbackReason fallback for unregistered statuses is intentional.
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            const reason = bareStatuses.includes(err.status) ? undefined : (reasonPhrases[err.status] ?? fallbackReason);
-            if (reason === undefined) {
-                return c.json({ statusCode: err.status, message: err.message }, err.status);
-            }
-            const body = fieldOrder === 'message-first'
-                ? { message: err.message, error: reason, statusCode: err.status }
-                : { statusCode: err.status, message: err.message, error: reason };
-            return c.json(body, err.status);
-        }
-        try {
-            onUnhandledError?.(err, c);
-        }
-        catch {
-            // Reporting must never change the behavior of the error response.
-        }
-        if (findMysqlDriverError(err)) {
-            logMysqlDriverError(err, 500);
-        }
-        else {
-            console.error(err);
-        }
-        return c.json(internalServerErrorBody, 500);
-    };
-}
-/**
- * Hono `notFound` handler that returns the canonical Express/NestJS unmatched-route 404 body.
- *
- * @remarks
- * Produces `{ message: "Cannot <METHOD> <path>", error: 'Not Found', statusCode: 404 }`, matching the
- * NestJS default 404 response so unmatched routes stay byte-identical.
- *
- * @param c - The Hono request context for the unmatched route.
- * @returns A 404 JSON response.
- *
- * @example
- * ```ts
- * app.notFound(nestNotFoundHandler);
- * ```
- */
-export function nestNotFoundHandler(c) {
-    return c.json({ message: `Cannot ${c.req.method} ${new URL(c.req.url).pathname}`, error: 'Not Found', statusCode: 404 }, 404);
-}

package/dist/payment/persistence.d.ts

@@ -1,24 +0,0 @@
-import type { SQL } from 'drizzle-orm';
-/**
- * `payment_failed` persistence helpers shared across the fleet.
- *
- * @remarks
- * `drizzle-orm` is a **peer** of this kit (the consumer resolves a single copy). These helpers only
- * build SQL fragments — the consumer's repository executes them, so it works regardless of the
- * consumer's DB access layer (`db.write` / `helper.query`).
- */
-/**
- * The `onDuplicateKeyUpdate.set` for an `insert(paymentFailed)…` that **never re-opens a `resolved`
- * row** — the idempotency guard against Stripe's delayed/out-of-order webhook redelivery leaving a
- * paid user with a permanent failure banner.
- *
- * @remarks
- * `receipt` is evaluated **before** `status` (SET is left→right and later columns see already-updated
- * ones), so both branch on the *pre-update* `payment_failed.status`. `type`/`user_id` are always
- * refreshed. Spread into the call:
- * `insert(paymentFailed).values(...).onDuplicateKeyUpdate({ set: reopenGuardedPaymentFailedSet() })`.
- *
- * Assumes the canonical column names (`type`, `user_id`, `status`, `receipt`) and the drizzle schema
- * property names (`type`, `userId`, `status`, `receipt`) used fleet-wide.
- */
-export declare function reopenGuardedPaymentFailedSet(): Record<'type' | 'userId' | 'status' | 'receipt', SQL>;

package/dist/payment/persistence.js

@@ -1,32 +0,0 @@
-import { sql } from 'drizzle-orm';
-/**
- * `payment_failed` persistence helpers shared across the fleet.
- *
- * @remarks
- * `drizzle-orm` is a **peer** of this kit (the consumer resolves a single copy). These helpers only
- * build SQL fragments — the consumer's repository executes them, so it works regardless of the
- * consumer's DB access layer (`db.write` / `helper.query`).
- */
-/**
- * The `onDuplicateKeyUpdate.set` for an `insert(paymentFailed)…` that **never re-opens a `resolved`
- * row** — the idempotency guard against Stripe's delayed/out-of-order webhook redelivery leaving a
- * paid user with a permanent failure banner.
- *
- * @remarks
- * `receipt` is evaluated **before** `status` (SET is left→right and later columns see already-updated
- * ones), so both branch on the *pre-update* `payment_failed.status`. `type`/`user_id` are always
- * refreshed. Spread into the call:
- * `insert(paymentFailed).values(...).onDuplicateKeyUpdate({ set: reopenGuardedPaymentFailedSet() })`.
- *
- * Assumes the canonical column names (`type`, `user_id`, `status`, `receipt`) and the drizzle schema
- * property names (`type`, `userId`, `status`, `receipt`) used fleet-wide.
- */
-export function reopenGuardedPaymentFailedSet() {
-    return {
-        type: sql `values(\`type\`)`,
-        userId: sql `values(\`user_id\`)`,
-        // resolved 行は理由も status も据え置き（再オープンしない）。status 代入より前に評価する。
-        receipt: sql `IF(\`payment_failed\`.\`status\` = 'resolved', \`payment_failed\`.\`receipt\`, values(\`receipt\`))`,
-        status: sql `IF(\`payment_failed\`.\`status\` = 'resolved', \`payment_failed\`.\`status\`, values(\`status\`))`,
-    };
-}