@rdlabo/workers-hono-kit 0.6.4 → 0.6.8

package/dist/index.d.ts

@@ -47,6 +47,16 @@ 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 { classifyStripeReconcile } from './stripe/reconcile.js';
+export type { StripeReconcileAction } from './stripe/reconcile.js';
+export { paymentFailureMessageJa, iapFailureKey, UNRESOLVED_PAYMENT_STATUSES } from './payment/failure.js';
+export type { PaymentFailureStatus, PaymentFailureType } from './payment/failure.js';
+export { classifyAppleRenewal, verifyAppleReceipt } from './iap/apple.js';
+export type { AppleRenewalState, AppleVerifyReceiptResponse, ApplePendingRenewalInfo, AppleLatestReceiptInfo, } from './iap/apple.js';
+export { classifyGoogleSubscription, getGoogleSubscription, googleAccessToken } from './iap/google.js';
+export type { GoogleSubscriptionState, GoogleSubscriptionPurchase, GoogleOAuthCredentials } from './iap/google.js';
 export { retryWhenDeadlock } from './db/retry.js';
 export { sendInChunks } from './queue/send.js';
 export type { QueueLike, QueueSendMessage } from './queue/send.js';

package/dist/index.js

@@ -36,6 +36,13 @@ 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 { 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';
+// in-app purchase (Apple / Google)
+export { classifyAppleRenewal, verifyAppleReceipt } from './iap/apple.js';
+export { classifyGoogleSubscription, getGoogleSubscription, googleAccessToken } from './iap/google.js';
 // db
 export { retryWhenDeadlock } from './db/retry.js';
 // queue

package/dist/payment/failure.d.ts

@@ -0,0 +1,62 @@
+import type { StripeFailureReason } from '../stripe/failure.js';
+/**
+ * Provider-agnostic status of a row in the `payment_failed` table.
+ *
+ * @remarks
+ * - `failed` — a charge failed (card decline / iOS billing-retry).
+ * - `action_required` — extra authentication pending (Stripe SCA).
+ * - `canceled` — the subscription was canceled or lapsed (all providers).
+ * - `resolved` — cleared after a later success / re-subscribe (kept for history).
+ */
+export type PaymentFailureStatus = 'failed' | 'action_required' | 'canceled' | 'resolved';
+/** Provider that produced a `payment_failed` row (matches the `type` column). */
+export type PaymentFailureType = 'stripe' | 'ios' | 'android';
+/**
+ * The statuses that still warrant a banner (everything except `resolved`).
+ * Use for `WHERE status IN (...)` on read / resolve queries so the set never drifts between repos.
+ *
+ * @remarks Readonly tuple — spread it for Drizzle's `inArray`: `inArray(col, [...UNRESOLVED_PAYMENT_STATUSES])`.
+ */
+export declare const UNRESOLVED_PAYMENT_STATUSES: readonly ["failed", "action_required", "canceled"];
+/**
+ * Render a user-facing Japanese message for a `payment_failed` row, across providers.
+ *
+ * @remarks
+ * Wraps {@link stripeFailureMessageJa} (decline_code → JA) and adds provider-agnostic wording for
+ * `canceled` (re-subscribe prompt) and for IAP `failed` (App Store / Google Play update prompt),
+ * which carry no Stripe `decline_code`. Message is generated on read so wording changes never
+ * require a data migration.
+ *
+ * @param input.status - The row status.
+ * @param input.type - The row `type` (stripe/ios/android); optional.
+ * @param input.reason - The stored Stripe reason (only meaningful for Stripe failures).
+ */
+export declare function paymentFailureMessageJa(input: {
+    status: PaymentFailureStatus;
+    /** The row `type` (stripe/ios/android). Typed as `string` since it comes from the DB column. */
+    type?: string | null;
+    reason?: StripeFailureReason | null;
+}): string;
+/**
+ * Build the `payment_failed.recursions_id` (PRIMARY KEY) with a per-type namespace.
+ *
+ * @remarks
+ * - iOS: `ios:${original_transaction_id}:${expires_date_ms}`. `original_transaction_id` is stable
+ *   across re-subscribes, so keying on it alone would let the resolved-reopen guard permanently mask
+ *   every event after the first. Including `expires_date_ms` makes each billing cycle a distinct row,
+ *   while the same cycle's daily reconcile (billing-retry) still converges to one row.
+ * - Android: `android:${orderId}` — Google issues a new orderId per subscription, so it is already
+ *   cycle-specific; the `android:` prefix only guards against cross-type PK collisions.
+ *
+ * Stripe rows use the invoice / subscription id directly (globally unique) and need no helper.
+ *
+ * @remarks Fits the fleet's `payment_failed.recursions_id` `varchar(50)` (iOS ≤ ~38, Android ≤ ~36 chars).
+ */
+export declare function iapFailureKey(input: {
+    platform: 'ios';
+    originalTransactionId: string;
+    expiresDateMs: string | number;
+} | {
+    platform: 'android';
+    orderId: string;
+}): string;

package/dist/payment/failure.js

@@ -0,0 +1,56 @@
+import { stripeFailureMessageJa } from '../stripe/failure.js';
+/**
+ * The statuses that still warrant a banner (everything except `resolved`).
+ * Use for `WHERE status IN (...)` on read / resolve queries so the set never drifts between repos.
+ *
+ * @remarks Readonly tuple — spread it for Drizzle's `inArray`: `inArray(col, [...UNRESOLVED_PAYMENT_STATUSES])`.
+ */
+export const UNRESOLVED_PAYMENT_STATUSES = ['failed', 'action_required', 'canceled'];
+const CANCELED_MESSAGE_JA = 'ご登録のプランは解約されています。引き続きプレミアム機能をご利用になるには、再度ご登録ください。';
+/** In-app-purchase の failed（カード無効）はプロバイダごとに更新導線が違うため文言を分ける。 */
+const IAP_FAILED_MESSAGE_JA = {
+    ios: 'お支払いの更新に失敗しました。App Store のお支払い情報をご確認のうえ、更新してください。',
+    android: 'お支払いの更新に失敗しました。Google Play のお支払い情報をご確認ください。',
+};
+/**
+ * Render a user-facing Japanese message for a `payment_failed` row, across providers.
+ *
+ * @remarks
+ * Wraps {@link stripeFailureMessageJa} (decline_code → JA) and adds provider-agnostic wording for
+ * `canceled` (re-subscribe prompt) and for IAP `failed` (App Store / Google Play update prompt),
+ * which carry no Stripe `decline_code`. Message is generated on read so wording changes never
+ * require a data migration.
+ *
+ * @param input.status - The row status.
+ * @param input.type - The row `type` (stripe/ios/android); optional.
+ * @param input.reason - The stored Stripe reason (only meaningful for Stripe failures).
+ */
+export function paymentFailureMessageJa(input) {
+    if (input.status === 'canceled') {
+        return CANCELED_MESSAGE_JA;
+    }
+    if (input.status === 'failed' && (input.type === 'ios' || input.type === 'android')) {
+        return IAP_FAILED_MESSAGE_JA[input.type];
+    }
+    return stripeFailureMessageJa(input.reason ?? null);
+}
+/**
+ * Build the `payment_failed.recursions_id` (PRIMARY KEY) with a per-type namespace.
+ *
+ * @remarks
+ * - iOS: `ios:${original_transaction_id}:${expires_date_ms}`. `original_transaction_id` is stable
+ *   across re-subscribes, so keying on it alone would let the resolved-reopen guard permanently mask
+ *   every event after the first. Including `expires_date_ms` makes each billing cycle a distinct row,
+ *   while the same cycle's daily reconcile (billing-retry) still converges to one row.
+ * - Android: `android:${orderId}` — Google issues a new orderId per subscription, so it is already
+ *   cycle-specific; the `android:` prefix only guards against cross-type PK collisions.
+ *
+ * Stripe rows use the invoice / subscription id directly (globally unique) and need no helper.
+ *
+ * @remarks Fits the fleet's `payment_failed.recursions_id` `varchar(50)` (iOS ≤ ~38, Android ≤ ~36 chars).
+ */
+export function iapFailureKey(input) {
+    return input.platform === 'ios'
+        ? `ios:${input.originalTransactionId}:${input.expiresDateMs}`
+        : `android:${input.orderId}`;
+}

package/dist/payment/persistence.d.ts

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

@@ -0,0 +1,32 @@
+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\`))`,
+    };
+}

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/dist/stripe/reconcile.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Stripe subscription reconcile classification.
+ *
+ * @remarks
+ * SDK-free / duck-typed (like `failure.ts`). Given an **expanded** subscription (its `latest_invoice`
+ * with the PaymentIntent resolved and the `customer`), decide what the `payment_failed` table should
+ * do. The consumer performs the DB writes; this only encodes the branch order.
+ *
+ * The branch order matters: subscription **termination is evaluated before `succeeded`**, so a
+ * voluntary cancel (cancel_at_period_end — its final invoice is paid, PaymentIntent=succeeded) is
+ * still recorded instead of being swallowed by the "succeeded → clear" branch.
+ *
+ * Both Stripe API shapes are accepted:
+ * - legacy `invoice.payment_intent` (id or expanded object)
+ * - v20+ `invoice.payments.data[0].payment.payment_intent`
+ * The PaymentIntent must be **expanded** (carry a `status`) for `clear`/dunning detection; when it is
+ * only an id, `canceled`/`trial` are still detected but `succeeded`/dunning fall through to `none`.
+ */
+/**
+ * What a reconcile pass should do with the `payment_failed` table for a subscription.
+ * - `trial` — trialing (paid invoice, no PaymentIntent). Consumer upserts payment; typically clears failures.
+ * - `clear` — active/trialing with a succeeded charge → resolve any open failure.
+ * - `canceled` — subscription ended (canceled/incomplete_expired) → record a `canceled` row.
+ * - `failed` — dunning with `requires_payment_method` → record a `failed` row.
+ * - `action_required` — dunning with `requires_action` (SCA) → record an `action_required` row.
+ * - `none` — nothing to record (e.g. active + not-yet-charged, or PaymentIntent not expanded).
+ */
+export type StripeReconcileAction = 'trial' | 'clear' | 'canceled' | 'failed' | 'action_required' | 'none';
+/**
+ * Classify an expanded Stripe subscription into a {@link StripeReconcileAction}.
+ *
+ * @param subscription - The subscription with `latest_invoice` + PaymentIntent expanded (duck-typed).
+ */
+export declare function classifyStripeReconcile(subscription: unknown): StripeReconcileAction;

package/dist/stripe/reconcile.js

@@ -0,0 +1,80 @@
+/**
+ * Stripe subscription reconcile classification.
+ *
+ * @remarks
+ * SDK-free / duck-typed (like `failure.ts`). Given an **expanded** subscription (its `latest_invoice`
+ * with the PaymentIntent resolved and the `customer`), decide what the `payment_failed` table should
+ * do. The consumer performs the DB writes; this only encodes the branch order.
+ *
+ * The branch order matters: subscription **termination is evaluated before `succeeded`**, so a
+ * voluntary cancel (cancel_at_period_end — its final invoice is paid, PaymentIntent=succeeded) is
+ * still recorded instead of being swallowed by the "succeeded → clear" branch.
+ *
+ * Both Stripe API shapes are accepted:
+ * - legacy `invoice.payment_intent` (id or expanded object)
+ * - v20+ `invoice.payments.data[0].payment.payment_intent`
+ * The PaymentIntent must be **expanded** (carry a `status`) for `clear`/dunning detection; when it is
+ * only an id, `canceled`/`trial` are still detected but `succeeded`/dunning fall through to `none`.
+ */
+const asRecord = (v) => typeof v === 'object' && v !== null ? v : null;
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
+const DUNNING_STATUSES = new Set(['past_due', 'unpaid', 'incomplete']);
+/** Resolve the PaymentIntent object/id from an invoice across Stripe API versions. */
+function resolvePaymentIntent(invoice) {
+    if (!invoice) {
+        return { present: false };
+    }
+    // legacy: invoice.payment_intent (id string or expanded object)
+    const direct = invoice.payment_intent;
+    if (direct !== null && direct !== undefined) {
+        return { present: true, status: str(asRecord(direct)?.status) };
+    }
+    // v20+: invoice.payments.data[0].payment.payment_intent
+    const payments = asRecord(invoice.payments);
+    const data = Array.isArray(payments?.data) ? payments.data : [];
+    const pi = asRecord(asRecord(asRecord(data[0])?.payment)?.payment_intent);
+    if (pi) {
+        return { present: true, status: str(pi.status) };
+    }
+    const piId = str(asRecord(asRecord(data[0])?.payment)?.payment_intent);
+    return { present: piId !== undefined, status: undefined };
+}
+/**
+ * Classify an expanded Stripe subscription into a {@link StripeReconcileAction}.
+ *
+ * @param subscription - The subscription with `latest_invoice` + PaymentIntent expanded (duck-typed).
+ */
+export function classifyStripeReconcile(subscription) {
+    const sub = asRecord(subscription);
+    if (!sub) {
+        return 'none';
+    }
+    const subStatus = str(sub.status);
+    const invoice = asRecord(sub.latest_invoice);
+    const invoiceStatus = str(invoice?.status);
+    const pi = resolvePaymentIntent(invoice);
+    // Termination first: evaluated before `trial` and before `succeeded`, so a canceled subscription is
+    // always recorded — whether its final invoice is paid (voluntary cancel, PI=succeeded), a trial
+    // (paid invoice, no PI), or the PaymentIntent is unexpanded. Otherwise it would be swallowed by the
+    // `trial` / `succeeded → clear` branches and the cancellation would never be recorded.
+    if (subStatus === 'canceled' || subStatus === 'incomplete_expired') {
+        return 'canceled';
+    }
+    if (invoiceStatus === 'paid' && !pi.present) {
+        return 'trial';
+    }
+    if (pi.present) {
+        if (pi.status === 'succeeded') {
+            return 'clear';
+        }
+        if (subStatus !== undefined && DUNNING_STATUSES.has(subStatus)) {
+            if (pi.status === 'requires_action') {
+                return 'action_required';
+            }
+            if (pi.status === 'requires_payment_method') {
+                return 'failed';
+            }
+        }
+    }
+    return 'none';
+}

package/package.json

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