@rdlabo/workers-hono-kit 0.6.10 → 0.6.13

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. |
@@ -83,6 +84,16 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `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 +206,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 +515,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

@@ -47,7 +47,7 @@ export { KVCache } from './cache/kv-cache.js';
 export type { KVNamespace, KVCacheOptions } from './cache/kv-cache.js';
 export { createStripeClient, verifyStripeWebhook } from './stripe/client.js';
 export type { CreateStripeClientOptions } from './stripe/client.js';
-export { extractStripeFailureReason, stripeFailureMessageJa, serializePaymentFailure, parsePaymentFailure, PaymentDeclinedError, toPaymentDeclinedError, } from './stripe/failure.js';
+export { extractStripeFailureReason, stripeFailureMessageJa, serializePaymentFailure, serializeIapFailureReason, parsePaymentFailure, PaymentDeclinedError, toPaymentDeclinedError, } from './stripe/failure.js';
 export type { StripeFailureReason, PaymentFailureSource, PaymentFailureRecord, PaymentFailureReason, IapFailureReason, PaymentDeclinedBody, } from './stripe/failure.js';
 export { classifyStripeReconcile } from './stripe/reconcile.js';
 export type { StripeReconcileAction } from './stripe/reconcile.js';

package/dist/index.js

@@ -36,7 +36,7 @@ export { createSentryErrorReporter } from './http/http-error.js';
 export { KVCache } from './cache/kv-cache.js';
 // stripe
 export { createStripeClient, verifyStripeWebhook } from './stripe/client.js';
-export { extractStripeFailureReason, stripeFailureMessageJa, serializePaymentFailure, parsePaymentFailure, PaymentDeclinedError, toPaymentDeclinedError, } from './stripe/failure.js';
+export { extractStripeFailureReason, stripeFailureMessageJa, serializePaymentFailure, serializeIapFailureReason, parsePaymentFailure, PaymentDeclinedError, toPaymentDeclinedError, } from './stripe/failure.js';
 export { classifyStripeReconcile } from './stripe/reconcile.js';
 // payment (provider-agnostic; web-standard only). reopenGuardedPaymentFailedSet is drizzle-based → './db'.
 export { paymentFailureMessageJa, iapFailureKey, UNRESOLVED_PAYMENT_STATUSES } from './payment/failure.js';

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/payment/failure.js

@@ -32,7 +32,7 @@ export function paymentFailureMessageJa(input) {
     if (input.status === 'failed' && (input.type === 'ios' || input.type === 'android')) {
         return IAP_FAILED_MESSAGE_JA[input.type];
     }
-    const stripeReason = input.reason && !('provider' in input.reason) ? input.reason : null;
+    const stripeReason = input.type === 'ios' || input.type === 'android' ? null : (input.reason ?? null);
     return stripeFailureMessageJa(stripeReason);
 }
 /**

package/dist/stripe/failure.d.ts

@@ -24,8 +24,6 @@ export interface StripeFailureReason {
 }
 /** Normalized reason persisted for an App Store / Google Play subscription failure. */
 export interface IapFailureReason {
-    /** Provider discriminator. */
-    provider: 'ios' | 'android';
     /** Stable machine-readable classification. */
     code: 'billing_retry' | 'auto_renew_off' | 'subscription_canceled' | 'subscription_gone';
     /** Provider response status code when present (Apple verifyReceipt status / Google error code). */
@@ -50,9 +48,10 @@ export type PaymentFailureSource = 'webhook.invoice.payment_failed' | 'webhook.i
  */
 export interface PaymentFailureRecord {
     reason: PaymentFailureReason;
-    source: PaymentFailureSource;
+    /** Capture path. Optional for IAP because `payment_failed.type` already identifies the provider/path. */
+    source?: PaymentFailureSource;
     /** ISO 8601 timestamp of when the failure was captured. */
-    occurredAt: string;
+    occurredAt?: string;
 }
 /**
  * Extract a normalized {@link StripeFailureReason} from a Stripe `PaymentIntent`, `Invoice`, a
@@ -86,6 +85,8 @@ export declare function stripeFailureMessageJa(reason: StripeFailureReason | nul
  * @returns A JSON string.
  */
 export declare function serializePaymentFailure(record: PaymentFailureRecord): string;
+/** Serialize an IAP reason directly, without redundant provider/source/timestamp wrappers. */
+export declare function serializeIapFailureReason(reason: IapFailureReason): string;
 /**
  * Parse a `payment_failed.receipt` value back into a {@link PaymentFailureRecord}.
  *

package/dist/stripe/failure.js

@@ -148,6 +148,10 @@ export function stripeFailureMessageJa(reason) {
 export function serializePaymentFailure(record) {
     return JSON.stringify(record);
 }
+/** Serialize an IAP reason directly, without redundant provider/source/timestamp wrappers. */
+export function serializeIapFailureReason(reason) {
+    return JSON.stringify(reason);
+}
 /**
  * Parse a `payment_failed.receipt` value back into a {@link PaymentFailureRecord}.
  *
@@ -161,10 +165,21 @@ export function parsePaymentFailure(receipt) {
     try {
         const parsed = JSON.parse(receipt);
         const r = asRecord(parsed);
-        if (!r || !asRecord(r.reason) || typeof r.source !== 'string' || typeof r.occurredAt !== 'string') {
+        if (!r) {
             return null;
         }
-        return parsed;
+        if (asRecord(r.reason)) {
+            if ((r.source !== undefined && typeof r.source !== 'string') ||
+                (r.occurredAt !== undefined && typeof r.occurredAt !== 'string')) {
+                return null;
+            }
+            return parsed;
+        }
+        // IAP rows store the reason itself. `code` is required so arbitrary JSON is not accepted as a reason.
+        if (typeof r.code === 'string') {
+            return { reason: parsed };
+        }
+        return null;
     }
     catch {
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.6.10",
+  "version": "0.6.13",
   "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\`))`,
-    };
-}