@rdlabo/workers-hono-kit 0.6.3 → 0.6.6

package/README.md

@@ -5,7 +5,7 @@ Infrastructure toolkit for building APIs on [Hono](https://hono.dev) + [Cloudfla
 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:
 
 - **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** via SigV4-signed `fetch` ([`aws4fetch`](https://github.com/mhart/aws4fetch)) — no AWS SDK.
+- **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.
 - **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.
@@ -56,6 +56,7 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `createSentryValidate(sentry)` | **Deprecated** — use `createValidate({ sentry })`. |
 | `zNum` / `zNumWithDefault` / `zNumOptional` / `zNumNullable` | Number-coercion zod schemas (mirror class-transformer `@Transform`). |
 | `getAuthenticationSecret<T>(options, secretId)` / `AwsSecretsOptions` | Fetch a secret from AWS Secrets Manager (SigV4 `fetch`, per-isolate cache). |
+| `getTemporaryCredentials(options)` / `GetTemporaryCredentialsOptions` / `StsCredentials` | STS `AssumeRole` via SigV4 `fetch` (global `sts.amazonaws.com`); returns temporary credentials for browser S3 uploads. |
 | `getCloudFrontSignedUrl(url, privateKeyPem, keyPairId, dateLessThan)` | CloudFront signed URL (canned policy, RSA-SHA1, URL-safe base64) — Web Crypto reimpl of `@aws-sdk/cloudfront-signer`, byte-identical query order. |
 | `JoseFirebaseVerifier` / `FirebaseVerifier` / `DecodedIdToken` | Firebase ID-token verification (`verifyIdToken`, `getUser`, `deleteUser`). |
 | `createRemoteFirebaseVerifier(projectId)` | Convenience factory: production verifier with a cached remote JWKS (verification only). |
@@ -271,6 +272,20 @@ const secret = await getAuthenticationSecret<MySecret>(
 );
 ```
 
+### STS AssumeRole (browser S3 uploads)
+
+```ts
+import { getTemporaryCredentials } from '@rdlabo/workers-hono-kit';
+
+const credentials = await getTemporaryCredentials({
+  accessKeyId: env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+  roleArn: 'arn:aws:iam::123456789012:role/s3-put-app-only-role',
+  roleSessionName: `session-${userId}-${Date.now()}`,
+});
+// Return credentials to the browser; PutObject uses @aws-sdk/client-s3 with AccessKeyId / …
+```
+
 ### Deadlock retry & HTTP helpers
 
 ```ts

package/dist/aws/sts.d.ts

@@ -0,0 +1,67 @@
+/**
+ * AWS credentials used to sign an STS `AssumeRole` request.
+ *
+ * @remarks
+ * Same shape as {@link AwsSecretsOptions} minus the required Secrets Manager region; STS defaults to
+ * the global endpoint (`us-east-1`) unless {@link GetTemporaryCredentialsOptions.region} is set.
+ */
+export interface GetTemporaryCredentialsOptions {
+    /** AWS access key ID of the caller principal that may AssumeRole. */
+    accessKeyId: string;
+    /** AWS secret access key of the caller principal. */
+    secretAccessKey: string;
+    /** Optional STS session token when the caller already holds temporary credentials. */
+    sessionToken?: string;
+    /** ARN of the role to assume (e.g. `arn:aws:iam::123:role/s3-put-app-only-role`). */
+    roleArn: string;
+    /** Session name recorded in CloudTrail (often `session-${userId}-${Date.now()}`). */
+    roleSessionName: string;
+    /**
+     * Credential lifetime in seconds.
+     * @defaultValue 900
+     */
+    durationSeconds?: number;
+    /**
+     * STS SigV4 signing region.
+     * @defaultValue us-east-1
+     */
+    region?: string;
+    /**
+     * STS endpoint URL.
+     * @defaultValue https://sts.amazonaws.com/
+     */
+    endpoint?: string;
+}
+/**
+ * Temporary credentials returned by STS `AssumeRole`.
+ *
+ * @remarks
+ * Field names match the STS XML response / `@aws-sdk/client-sts` `Credentials` shape so browser
+ * apps can pass them straight into `@aws-sdk/client-s3` (`AccessKeyId` → `accessKeyId`, etc.).
+ */
+export interface StsCredentials {
+    AccessKeyId?: string;
+    SecretAccessKey?: string;
+    SessionToken?: string;
+    Expiration?: Date;
+}
+/**
+ * Call STS `AssumeRole` via SigV4-signed `fetch` (aws4fetch) and return temporary credentials.
+ *
+ * Port of winecode / airlec browser-upload credential issuance — no AWS SDK. The consuming app
+ * supplies `roleArn` and `roleSessionName`; the kit only performs the signed STS request and XML parse.
+ *
+ * @param options - Caller AWS keys plus assume-role parameters.
+ * @returns Temporary credentials for browser or edge PutObject / GetObject.
+ * @throws Error When the STS response is not OK.
+ * @example
+ * ```ts
+ * const credentials = await getTemporaryCredentials({
+ *   accessKeyId: env.AWS_ACCESS_KEY_ID,
+ *   secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+ *   roleArn: 'arn:aws:iam::123:role/s3-put-app-only-role',
+ *   roleSessionName: `session-${userId}-${Date.now()}`,
+ * });
+ * ```
+ */
+export declare function getTemporaryCredentials(options: GetTemporaryCredentialsOptions): Promise<StsCredentials>;

package/dist/aws/sts.js

@@ -0,0 +1,66 @@
+import { AwsClient } from 'aws4fetch';
+/** STS SigV4 signing region for the global endpoint (`sts.amazonaws.com`). */
+const DEFAULT_STS_REGION = 'us-east-1';
+/** winecode / airlec default — 15 minutes. */
+const DEFAULT_DURATION_SECONDS = 900;
+const STS_API_VERSION = '2011-06-15';
+/** Global STS endpoint (unchanged from winecode AwsService). */
+const DEFAULT_STS_ENDPOINT = 'https://sts.amazonaws.com/';
+/**
+ * Call STS `AssumeRole` via SigV4-signed `fetch` (aws4fetch) and return temporary credentials.
+ *
+ * Port of winecode / airlec browser-upload credential issuance — no AWS SDK. The consuming app
+ * supplies `roleArn` and `roleSessionName`; the kit only performs the signed STS request and XML parse.
+ *
+ * @param options - Caller AWS keys plus assume-role parameters.
+ * @returns Temporary credentials for browser or edge PutObject / GetObject.
+ * @throws Error When the STS response is not OK.
+ * @example
+ * ```ts
+ * const credentials = await getTemporaryCredentials({
+ *   accessKeyId: env.AWS_ACCESS_KEY_ID,
+ *   secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+ *   roleArn: 'arn:aws:iam::123:role/s3-put-app-only-role',
+ *   roleSessionName: `session-${userId}-${Date.now()}`,
+ * });
+ * ```
+ */
+export async function getTemporaryCredentials(options) {
+    const region = options.region ?? DEFAULT_STS_REGION;
+    const durationSeconds = options.durationSeconds ?? DEFAULT_DURATION_SECONDS;
+    const endpoint = options.endpoint ?? DEFAULT_STS_ENDPOINT;
+    const params = new URLSearchParams({
+        Action: 'AssumeRole',
+        Version: STS_API_VERSION,
+        RoleArn: options.roleArn,
+        RoleSessionName: options.roleSessionName,
+        DurationSeconds: String(durationSeconds),
+    });
+    const aws = new AwsClient({
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey,
+        sessionToken: options.sessionToken,
+        region,
+        service: 'sts',
+    });
+    const response = await aws.fetch(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: params.toString(),
+    });
+    const xml = await response.text();
+    if (!response.ok) {
+        throw new Error(`STS AssumeRole failed: ${response.status} ${xml}`);
+    }
+    const pick = (tag) => {
+        const m = new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml);
+        return m ? m[1] : undefined;
+    };
+    const expiration = pick('Expiration');
+    return {
+        AccessKeyId: pick('AccessKeyId'),
+        SecretAccessKey: pick('SecretAccessKey'),
+        SessionToken: pick('SessionToken'),
+        Expiration: expiration ? new Date(expiration) : undefined,
+    };
+}

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

@@ -0,0 +1,149 @@
+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

@@ -0,0 +1,120 @@
+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/index.d.ts

@@ -47,6 +47,8 @@ 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 type { StripeFailureReason, PaymentFailureSource, PaymentFailureRecord, PaymentDeclinedBody, } from './stripe/failure.js';
 export { retryWhenDeadlock } from './db/retry.js';
 export { sendInChunks } from './queue/send.js';
 export type { QueueLike, QueueSendMessage } from './queue/send.js';
@@ -59,6 +61,8 @@ export type { AiGatewayConfig, AiGatewayProvider, AiGatewayBinding, AiGateway, A
 export { getAuthenticationSecret } from './aws/secrets-manager.js';
 export type { AwsSecretsOptions } from './aws/secrets-manager.js';
 export { getCloudFrontSignedUrl } from './aws/cloudfront.js';
+export { getTemporaryCredentials } from './aws/sts.js';
+export type { GetTemporaryCredentialsOptions, StsCredentials } from './aws/sts.js';
 export type { DecodedIdToken, FirebaseVerifier } from './firebase/firebase-verifier.js';
 export { JoseFirebaseVerifier, SECURETOKEN_JWK_URL } from './firebase/jose-firebase-verifier.js';
 export { IdentityToolkit } from './firebase/identity-toolkit.js';

package/dist/index.js

@@ -36,6 +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';
 // db
 export { retryWhenDeadlock } from './db/retry.js';
 // queue
@@ -47,6 +48,7 @@ export { createAiGatewayProvider } from './ai/gateway.js';
 // aws
 export { getAuthenticationSecret } from './aws/secrets-manager.js';
 export { getCloudFrontSignedUrl } from './aws/cloudfront.js';
+export { getTemporaryCredentials } from './aws/sts.js';
 export { JoseFirebaseVerifier, SECURETOKEN_JWK_URL } from './firebase/jose-firebase-verifier.js';
 export { IdentityToolkit } from './firebase/identity-toolkit.js';
 export { createRemoteFirebaseVerifier, createServiceAccountVerifier } from './firebase/remote-verifier.js';

package/dist/stripe/failure.d.ts

@@ -0,0 +1,108 @@
+import { HTTPException } from 'hono/http-exception';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+/**
+ * Normalized, provider-agnostic description of a failed Stripe payment.
+ *
+ * @remarks
+ * Extracted from a Stripe `PaymentIntent`, `Invoice`, or a thrown `StripeCardError` by
+ * {@link extractStripeFailureReason}. Fields are all optional because Stripe does not always populate
+ * a decline reason (e.g. a Strong Customer Authentication challenge carries no `decline_code`).
+ */
+export interface StripeFailureReason {
+    /** `last_payment_error.code`, e.g. `card_declined` / `authentication_required`. */
+    code?: string;
+    /** `last_payment_error.decline_code`, e.g. `insufficient_funds` / `expired_card`. */
+    declineCode?: string;
+    /** Stripe's original (English) failure message. Stored for debugging; never shown to users. */
+    message?: string;
+    /** Id of the PaymentIntent the failure originated from, when resolvable. */
+    paymentIntentId?: string;
+    /** Id of the Invoice the failure originated from, when resolvable. */
+    invoiceId?: string;
+    /** Id of the Subscription the failing invoice belongs to, when resolvable. */
+    subscriptionId?: string;
+}
+/** Where a {@link PaymentFailureRecord} was captured. */
+export type PaymentFailureSource = 'webhook.invoice.payment_failed' | 'webhook.invoice.payment_action_required' | 'reconcile' | 'checkout' | 'iap';
+/**
+ * A payment failure as persisted to the `payment_failed.receipt` column (JSON string).
+ *
+ * @remarks
+ * Only the raw {@link StripeFailureReason} is stored — the user-facing Japanese message is generated
+ * on read via {@link stripeFailureMessageJa} so that wording changes never require a data migration.
+ */
+export interface PaymentFailureRecord {
+    reason: StripeFailureReason;
+    source: PaymentFailureSource;
+    /** ISO 8601 timestamp of when the failure was captured. */
+    occurredAt: string;
+}
+/**
+ * Extract a normalized {@link StripeFailureReason} from a Stripe `PaymentIntent`, `Invoice`, a
+ * `{ paymentIntent, invoice }` pair, or a thrown Stripe error.
+ *
+ * @remarks
+ * The Stripe SDK is intentionally **not** imported — inputs are typed `unknown` and inspected by
+ * duck typing (Stripe objects carry an `object` discriminator: `'payment_intent'` / `'invoice'`).
+ * This keeps the helper immune to Stripe SDK version differences between this kit and its consumers,
+ * matching the existing `isPermanentPaymentError` approach in the payment services.
+ *
+ * @param source - A PaymentIntent, Invoice, `{ paymentIntent?, invoice? }`, or thrown Stripe error.
+ * @returns The extracted reason, or `null` when nothing identifiable could be found.
+ */
+export declare function extractStripeFailureReason(source: unknown): StripeFailureReason | null;
+/**
+ * Render a {@link StripeFailureReason} as a single-sentence Japanese message safe to show to users.
+ *
+ * @remarks
+ * `decline_code` wins over `code`; anything unmapped (including `null`) falls back to a generic
+ * message. Fraud-related decline codes are deliberately masked with a generic phrase.
+ *
+ * @param reason - The extracted failure reason, or `null`.
+ * @returns A user-facing Japanese message.
+ */
+export declare function stripeFailureMessageJa(reason: StripeFailureReason | null): string;
+/**
+ * Serialize a {@link PaymentFailureRecord} for storage in the `payment_failed.receipt` column.
+ *
+ * @param record - The failure record to serialize.
+ * @returns A JSON string.
+ */
+export declare function serializePaymentFailure(record: PaymentFailureRecord): string;
+/**
+ * Parse a `payment_failed.receipt` value back into a {@link PaymentFailureRecord}.
+ *
+ * @param receipt - The stored JSON string, or `null`/`undefined`.
+ * @returns The parsed record, or `null` when absent or malformed.
+ */
+export declare function parsePaymentFailure(receipt: string | null | undefined): PaymentFailureRecord | null;
+/** Response body carried by {@link PaymentDeclinedError}. */
+export interface PaymentDeclinedBody {
+    statusCode: number;
+    /** User-facing Japanese message. */
+    message: string;
+    code?: string;
+    declineCode?: string;
+}
+/**
+ * HTTP error for a synchronous card decline, carrying a user-facing Japanese message.
+ *
+ * @remarks
+ * Extends Hono's `HTTPException` and exposes a `body`, so `createHttpErrorHandler` returns that body
+ * verbatim (see {@link createHttpErrorHandler}). Defaults to `400` rather than the semantically
+ * correct `402` so it rides the fleet's existing client interceptor, which surfaces `4xx` bodies with
+ * a `message` to the user.
+ */
+export declare class PaymentDeclinedError extends HTTPException {
+    readonly body: PaymentDeclinedBody;
+    constructor(reason: StripeFailureReason | null, status?: ContentfulStatusCode);
+}
+/**
+ * Convert a thrown Stripe error into a {@link PaymentDeclinedError}, or `null` when it is not a card
+ * decline (the caller should re-throw so it maps to a generic 500).
+ *
+ * @param error - The value thrown by a Stripe SDK call.
+ * @param status - HTTP status for the resulting error; defaults to `400` (see {@link PaymentDeclinedError}).
+ * @returns A {@link PaymentDeclinedError}, or `null` when `error` is not a card decline.
+ */
+export declare function toPaymentDeclinedError(error: unknown, status?: ContentfulStatusCode): PaymentDeclinedError | null;

package/dist/stripe/failure.js

@@ -0,0 +1,208 @@
+import { HTTPException } from 'hono/http-exception';
+const asRecord = (v) => typeof v === 'object' && v !== null ? v : null;
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
+/** Pull `{ code, decline_code, message }` out of a Stripe error-shaped object, or `null` if empty. */
+function readErrorShape(v) {
+    const r = asRecord(v);
+    if (!r) {
+        return null;
+    }
+    const code = str(r.code);
+    const declineCode = str(r.decline_code);
+    const message = str(r.message);
+    if (!code && !declineCode && !message) {
+        return null;
+    }
+    return { code, declineCode, message };
+}
+/** Resolve a Stripe reference (id string or expanded object with an `id`) to its id string. */
+function refId(v) {
+    if (typeof v === 'string') {
+        return str(v);
+    }
+    return str(asRecord(v)?.id);
+}
+/**
+ * Extract a normalized {@link StripeFailureReason} from a Stripe `PaymentIntent`, `Invoice`, a
+ * `{ paymentIntent, invoice }` pair, or a thrown Stripe error.
+ *
+ * @remarks
+ * The Stripe SDK is intentionally **not** imported — inputs are typed `unknown` and inspected by
+ * duck typing (Stripe objects carry an `object` discriminator: `'payment_intent'` / `'invoice'`).
+ * This keeps the helper immune to Stripe SDK version differences between this kit and its consumers,
+ * matching the existing `isPermanentPaymentError` approach in the payment services.
+ *
+ * @param source - A PaymentIntent, Invoice, `{ paymentIntent?, invoice? }`, or thrown Stripe error.
+ * @returns The extracted reason, or `null` when nothing identifiable could be found.
+ */
+export function extractStripeFailureReason(source) {
+    const root = asRecord(source);
+    if (!root) {
+        return null;
+    }
+    let paymentIntent = null;
+    let invoice = null;
+    let thrown = null;
+    if (root.paymentIntent !== undefined || root.invoice !== undefined) {
+        // Normalized container: { paymentIntent?, invoice? }.
+        paymentIntent = asRecord(root.paymentIntent);
+        invoice = asRecord(root.invoice);
+    }
+    else if (str(root.object) === 'payment_intent') {
+        paymentIntent = root;
+    }
+    else if (str(root.object) === 'invoice') {
+        invoice = root;
+    }
+    else if (str(root.code) || str(root.decline_code) || root.type === 'StripeCardError') {
+        // A thrown Stripe error; it may carry an expanded PaymentIntent.
+        thrown = root;
+        paymentIntent = asRecord(root.payment_intent);
+    }
+    // An invoice may embed its PaymentIntent (when expanded).
+    if (invoice && !paymentIntent) {
+        paymentIntent = asRecord(invoice.payment_intent);
+    }
+    const errorShape = readErrorShape(paymentIntent?.last_payment_error) ??
+        readErrorShape(invoice?.last_finalization_error) ??
+        (thrown ? readErrorShape(thrown) : null);
+    const reason = {
+        code: errorShape?.code,
+        declineCode: errorShape?.declineCode,
+        message: errorShape?.message,
+        paymentIntentId: refId(paymentIntent?.id ?? thrown?.payment_intent),
+        invoiceId: refId(invoice?.id),
+        subscriptionId: refId(invoice?.subscription),
+    };
+    // Strong Customer Authentication: no decline_code, but the intent is stuck on `requires_action`.
+    if (!reason.code && !reason.declineCode && str(paymentIntent?.status) === 'requires_action') {
+        reason.code = 'authentication_required';
+    }
+    const hasAny = reason.code ??
+        reason.declineCode ??
+        reason.message ??
+        reason.paymentIntentId ??
+        reason.invoiceId ??
+        reason.subscriptionId;
+    return hasAny ? reason : null;
+}
+const GENERIC_MESSAGE_JA = '前回のカード決済に失敗しました。カード情報をご確認のうえ、再度お試しください。';
+const FRAUD_MESSAGE_JA = 'カードがご利用いただけませんでした。カード会社にお問い合わせいただくか、別のカードをお試しください。';
+/** decline_code → Japanese, taking precedence over {@link CODE_MESSAGES_JA}. */
+const DECLINE_CODE_MESSAGES_JA = {
+    insufficient_funds: '残高不足のためカードが承認されませんでした。別のカードをお試しください。',
+    expired_card: 'カードの有効期限が切れています。カード情報を更新してください。',
+    incorrect_cvc: 'セキュリティコード（CVC）が正しくありません。カード情報をご確認ください。',
+    incorrect_number: 'カード番号が正しくありません。カード情報をご確認ください。',
+    card_not_supported: 'このカードはご利用いただけません。別のカードをお試しください。',
+    currency_not_supported: 'このカードは対象の通貨に対応していません。別のカードをお試しください。',
+    card_velocity_exceeded: 'ご利用限度を超えたためカードが承認されませんでした。時間をおいて再度お試しください。',
+    withdrawal_count_limit_exceeded: 'ご利用限度を超えたためカードが承認されませんでした。時間をおいて再度お試しください。',
+    processing_error: '決済処理中にエラーが発生しました。時間をおいて再度お試しください。',
+    try_again_later: '一時的な理由でカードが承認されませんでした。時間をおいて再度お試しください。',
+    // Fraud / security signals are collapsed to a generic message (Stripe recommends not revealing the reason).
+    lost_card: FRAUD_MESSAGE_JA,
+    stolen_card: FRAUD_MESSAGE_JA,
+    pickup_card: FRAUD_MESSAGE_JA,
+    do_not_honor: FRAUD_MESSAGE_JA,
+    generic_decline: FRAUD_MESSAGE_JA,
+    fraudulent: FRAUD_MESSAGE_JA,
+};
+/** last_payment_error.code → Japanese, used when no decline_code mapping matched. */
+const CODE_MESSAGES_JA = {
+    card_declined: FRAUD_MESSAGE_JA,
+    expired_card: 'カードの有効期限が切れています。カード情報を更新してください。',
+    incorrect_cvc: 'セキュリティコード（CVC）が正しくありません。カード情報をご確認ください。',
+    incorrect_number: 'カード番号が正しくありません。カード情報をご確認ください。',
+    processing_error: '決済処理中にエラーが発生しました。時間をおいて再度お試しください。',
+    authentication_required: 'カード認証（3Dセキュア）が必要です。お手数ですが、もう一度お手続きをお願いします。',
+};
+/**
+ * Render a {@link StripeFailureReason} as a single-sentence Japanese message safe to show to users.
+ *
+ * @remarks
+ * `decline_code` wins over `code`; anything unmapped (including `null`) falls back to a generic
+ * message. Fraud-related decline codes are deliberately masked with a generic phrase.
+ *
+ * @param reason - The extracted failure reason, or `null`.
+ * @returns A user-facing Japanese message.
+ */
+export function stripeFailureMessageJa(reason) {
+    if (!reason) {
+        return GENERIC_MESSAGE_JA;
+    }
+    if (reason.declineCode && DECLINE_CODE_MESSAGES_JA[reason.declineCode]) {
+        return DECLINE_CODE_MESSAGES_JA[reason.declineCode];
+    }
+    if (reason.code && CODE_MESSAGES_JA[reason.code]) {
+        return CODE_MESSAGES_JA[reason.code];
+    }
+    return GENERIC_MESSAGE_JA;
+}
+/**
+ * Serialize a {@link PaymentFailureRecord} for storage in the `payment_failed.receipt` column.
+ *
+ * @param record - The failure record to serialize.
+ * @returns A JSON string.
+ */
+export function serializePaymentFailure(record) {
+    return JSON.stringify(record);
+}
+/**
+ * Parse a `payment_failed.receipt` value back into a {@link PaymentFailureRecord}.
+ *
+ * @param receipt - The stored JSON string, or `null`/`undefined`.
+ * @returns The parsed record, or `null` when absent or malformed.
+ */
+export function parsePaymentFailure(receipt) {
+    if (!receipt) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(receipt);
+        const r = asRecord(parsed);
+        if (!r || !asRecord(r.reason) || typeof r.source !== 'string' || typeof r.occurredAt !== 'string') {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * HTTP error for a synchronous card decline, carrying a user-facing Japanese message.
+ *
+ * @remarks
+ * Extends Hono's `HTTPException` and exposes a `body`, so `createHttpErrorHandler` returns that body
+ * verbatim (see {@link createHttpErrorHandler}). Defaults to `400` rather than the semantically
+ * correct `402` so it rides the fleet's existing client interceptor, which surfaces `4xx` bodies with
+ * a `message` to the user.
+ */
+export class PaymentDeclinedError extends HTTPException {
+    body;
+    constructor(reason, status = 400) {
+        const message = stripeFailureMessageJa(reason);
+        super(status, { message });
+        this.body = { statusCode: status, message, code: reason?.code, declineCode: reason?.declineCode };
+    }
+}
+/**
+ * Convert a thrown Stripe error into a {@link PaymentDeclinedError}, or `null` when it is not a card
+ * decline (the caller should re-throw so it maps to a generic 500).
+ *
+ * @param error - The value thrown by a Stripe SDK call.
+ * @param status - HTTP status for the resulting error; defaults to `400` (see {@link PaymentDeclinedError}).
+ * @returns A {@link PaymentDeclinedError}, or `null` when `error` is not a card decline.
+ */
+export function toPaymentDeclinedError(error, status = 400) {
+    const r = asRecord(error);
+    if (!r) {
+        return null;
+    }
+    const isCardError = r.type === 'StripeCardError' || !!str(r.decline_code) || str(r.code) === 'card_declined';
+    if (!isCardError) {
+        return null;
+    }
+    return new PaymentDeclinedError(extractStripeFailureReason(error), status);
+}

package/package.json

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