@rdlabo/workers-hono-kit 0.6.6 → 0.6.9

package/dist/db/index.d.ts

@@ -24,3 +24,4 @@ export { DRIZZLE_ORM_OPTIONS, honoDrizzleConfig, resolveDbSecret } from './orm-c
 export type { HonoDrizzleConfigOptions, ResolvedDbSecret } from './orm-config.js';
 export { baselineMigrations, readBaselineEntry } from './migrate.js';
 export type { BaselineMigrationsOptions, BaselineResult, BaselineEntry } from './migrate.js';
+export { reopenGuardedPaymentFailedSet } from './payment-failed.js';

package/dist/db/index.js

@@ -18,3 +18,4 @@ export { coerceDecimalNumber, decimalNumberParams } from './decimal.js';
 export { jstTimestamp, jstDatetime, jstDate, decimalNumber, jstOnUpdateNow } from './columns.js';
 export { DRIZZLE_ORM_OPTIONS, honoDrizzleConfig, resolveDbSecret } from './orm-config.js';
 export { baselineMigrations, readBaselineEntry } from './migrate.js';
+export { reopenGuardedPaymentFailedSet } from './payment-failed.js';

package/dist/db/payment-failed.d.ts

@@ -0,0 +1,25 @@
+import type { SQL } from 'drizzle-orm';
+/**
+ * `payment_failed` persistence helpers (MySQL / Drizzle).
+ *
+ * @remarks
+ * Lives in the `./db` subpath because it imports `drizzle-orm` (a peer); the web-standard root export
+ * must stay free of ORM deps. The helper only builds 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` (Drizzle emits the SET clause in the object's insertion
+ * order and MySQL evaluates it left→right, so later columns would otherwise see the already-updated
+ * `status`). 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/db/payment-failed.js

@@ -0,0 +1,33 @@
+import { sql } from 'drizzle-orm';
+/**
+ * `payment_failed` persistence helpers (MySQL / Drizzle).
+ *
+ * @remarks
+ * Lives in the `./db` subpath because it imports `drizzle-orm` (a peer); the web-standard root export
+ * must stay free of ORM deps. The helper only builds 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` (Drizzle emits the SET clause in the object's insertion
+ * order and MySQL evaluates it left→right, so later columns would otherwise see the already-updated
+ * `status`). 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/iap/apple.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Apple App Store (StoreKit / verifyReceipt) helpers.
+ *
+ * @remarks
+ * Provider-agnostic and SDK-free: inputs are duck-typed `unknown` JSON (Apple ships no SDK), matching
+ * the `stripe/failure.ts` approach. `classifyAppleRenewal` maps a verifyReceipt response to a renewal
+ * state; the consumer decides how to persist it (billing_retry → `failed`, lapsed → `canceled`,
+ * active → resolve). `verifyAppleReceipt` performs the production→sandbox verification call.
+ */
+/** Apple `pending_renewal_info[]` entry (fields consumed here). */
+export interface ApplePendingRenewalInfo {
+    /** Links this renewal info to a subscription group / receipt (used to pick the matching entry). */
+    original_transaction_id?: string;
+    /** `'1'` while Apple is retrying billing because the payment method failed (= card invalid). */
+    is_in_billing_retry_period?: string;
+    /** `'0'` = auto-renew turned off (will lapse at period end). */
+    auto_renew_status?: string;
+    [key: string]: unknown;
+}
+/** Apple `latest_receipt_info[]` entry (fields consumed here). */
+export interface AppleLatestReceiptInfo {
+    original_transaction_id?: string;
+    /** Subscription expiry as epoch-ms string (stable regardless of the `expires_date` string format). */
+    expires_date_ms?: string;
+    [key: string]: unknown;
+}
+/** Apple `verifyReceipt` response (fields consumed here). */
+export interface AppleVerifyReceiptResponse {
+    status?: number;
+    environment?: string;
+    latest_receipt_info?: AppleLatestReceiptInfo[];
+    pending_renewal_info?: ApplePendingRenewalInfo[];
+    [key: string]: unknown;
+}
+/**
+ * Renewal state derived from an Apple verifyReceipt response.
+ * - `billing_retry` — Apple is retrying a failed payment (card invalid) → persist as `failed`.
+ * - `lapsed` — auto-renew off and expired → persist as `canceled`.
+ * - `active` — a valid (non-expired) subscription → resolve any open failure.
+ * - `unknown` — indeterminate (no receipt, or expired with auto-renew on and no retry) → no-op.
+ */
+export type AppleRenewalState = 'billing_retry' | 'lapsed' | 'active' | 'unknown';
+/**
+ * Classify an Apple verifyReceipt response into an {@link AppleRenewalState}.
+ *
+ * @remarks
+ * The most recent renewal (max `expires_date_ms`) is used regardless of array order. Sandbox is NOT
+ * filtered here — the consumer should skip `environment === 'Sandbox'` before persisting to a
+ * production table (see {@link AppleVerifyReceiptResponse.environment}).
+ *
+ * @param verify - The verifyReceipt response (duck-typed).
+ * @param now - Current epoch-ms (`Date.now()`); injected for determinism/testing.
+ * @returns The state plus the latest `original_transaction_id` / `expires_date_ms` (for the row key).
+ */
+export declare function classifyAppleRenewal(verify: unknown, now: number): {
+    state: AppleRenewalState;
+    originalTransactionId?: string;
+    expiresDateMs?: string;
+};
+/**
+ * Verify an App Store receipt against Apple, falling back from production to sandbox.
+ *
+ * @remarks
+ * Mirrors the fleet's long-standing verify flow: POST to the production endpoint, and if
+ * `status !== 0` retry against sandbox. Returns `null` when both reject. The `password` (shared
+ * secret) is per-app and must be injected. `fetchImpl` is injectable for tests.
+ *
+ * @remarks Caveat: any non-zero `status` (including Apple's *retryable* 21005/21009) collapses to
+ * `null`, so a transient Apple outage is indistinguishable from a genuinely invalid receipt. Do not
+ * treat `null` as "subscription gone" without other signals. Also throws if a response is not JSON.
+ *
+ * @returns The parsed response, or `null` for an invalid (or unverifiable) receipt.
+ */
+export declare function verifyAppleReceipt(receipt: string, opts: {
+    password: string;
+    fetchImpl?: typeof fetch;
+}): Promise<AppleVerifyReceiptResponse | null>;

package/dist/iap/apple.js

@@ -0,0 +1,84 @@
+/**
+ * Apple App Store (StoreKit / verifyReceipt) helpers.
+ *
+ * @remarks
+ * Provider-agnostic and SDK-free: inputs are duck-typed `unknown` JSON (Apple ships no SDK), matching
+ * the `stripe/failure.ts` approach. `classifyAppleRenewal` maps a verifyReceipt response to a renewal
+ * state; the consumer decides how to persist it (billing_retry → `failed`, lapsed → `canceled`,
+ * active → resolve). `verifyAppleReceipt` performs the production→sandbox verification call.
+ */
+const asRecord = (v) => typeof v === 'object' && v !== null ? v : null;
+const toArray = (v) => (Array.isArray(v) ? v : []);
+/**
+ * Classify an Apple verifyReceipt response into an {@link AppleRenewalState}.
+ *
+ * @remarks
+ * The most recent renewal (max `expires_date_ms`) is used regardless of array order. Sandbox is NOT
+ * filtered here — the consumer should skip `environment === 'Sandbox'` before persisting to a
+ * production table (see {@link AppleVerifyReceiptResponse.environment}).
+ *
+ * @param verify - The verifyReceipt response (duck-typed).
+ * @param now - Current epoch-ms (`Date.now()`); injected for determinism/testing.
+ * @returns The state plus the latest `original_transaction_id` / `expires_date_ms` (for the row key).
+ */
+export function classifyAppleRenewal(verify, now) {
+    const v = asRecord(verify);
+    // 消耗型など expires_date_ms 欠損エントリを除外してから最新（max expires）を選ぶ。
+    // 欠損値を Number() すると NaN で比較が常に false になり、先頭の欠損行が最後まで残って
+    // 誤って 'active'（isExpired=false）を返すため、有効な expires を持つ行だけを対象にする。
+    const infos = toArray(v?.latest_receipt_info).filter((e) => Number.isFinite(Number(e.expires_date_ms)));
+    const latest = infos.reduce((acc, cur) => {
+        if (!acc) {
+            return cur;
+        }
+        return Number(cur.expires_date_ms) > Number(acc.expires_date_ms) ? cur : acc;
+    }, undefined);
+    const originalTransactionId = latest?.original_transaction_id;
+    if (!latest || !originalTransactionId) {
+        return { state: 'unknown' };
+    }
+    // 複数サブスク商品時に別商品の renewal info を読まないよう、latest と同じ original_transaction_id の
+    // pending エントリを優先（無ければ先頭にフォールバック）。
+    const pendingArr = toArray(v?.pending_renewal_info);
+    const pending = pendingArr.find((p) => p.original_transaction_id === originalTransactionId) ?? pendingArr.at(0);
+    const expiresMs = Number(latest.expires_date_ms);
+    const isExpired = Number.isFinite(expiresMs) && expiresMs < now;
+    const base = { originalTransactionId, expiresDateMs: latest.expires_date_ms };
+    if (pending?.is_in_billing_retry_period === '1') {
+        return { state: 'billing_retry', ...base };
+    }
+    if (pending?.auto_renew_status === '0' && isExpired) {
+        return { state: 'lapsed', ...base };
+    }
+    if (!isExpired) {
+        return { state: 'active', ...base };
+    }
+    return { state: 'unknown', ...base };
+}
+/**
+ * Verify an App Store receipt against Apple, falling back from production to sandbox.
+ *
+ * @remarks
+ * Mirrors the fleet's long-standing verify flow: POST to the production endpoint, and if
+ * `status !== 0` retry against sandbox. Returns `null` when both reject. The `password` (shared
+ * secret) is per-app and must be injected. `fetchImpl` is injectable for tests.
+ *
+ * @remarks Caveat: any non-zero `status` (including Apple's *retryable* 21005/21009) collapses to
+ * `null`, so a transient Apple outage is indistinguishable from a genuinely invalid receipt. Do not
+ * treat `null` as "subscription gone" without other signals. Also throws if a response is not JSON.
+ *
+ * @returns The parsed response, or `null` for an invalid (or unverifiable) receipt.
+ */
+export async function verifyAppleReceipt(receipt, opts) {
+    const body = JSON.stringify({ 'receipt-data': receipt, password: opts.password });
+    const doFetch = opts.fetchImpl ?? fetch;
+    const post = (url) => doFetch(url, { method: 'POST', body }).then((r) => r.json());
+    let verify = await post('https://buy.itunes.apple.com/verifyReceipt');
+    if (verify.status !== 0) {
+        verify = await post('https://sandbox.itunes.apple.com/verifyReceipt');
+        if (verify.status !== 0) {
+            return null;
+        }
+    }
+    return verify;
+}

package/dist/iap/google.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Google Play (Android Publisher) subscription helpers.
+ *
+ * @remarks
+ * SDK-free and duck-typed like {@link ./apple.ts}. `classifyGoogleSubscription` maps a
+ * `purchases.subscriptions.get` response (or its 410 error) to a state; the consumer persists it
+ * (canceled/gone → `canceled`, active → resolve). `getGoogleSubscription` / `googleAccessToken`
+ * perform the OAuth + Android Publisher calls.
+ */
+/** Android Publisher `purchases.subscriptions.get` response (fields consumed here). */
+export interface GoogleSubscriptionPurchase {
+    startTimeMillis?: string;
+    expiryTimeMillis?: string;
+    /** `false` once the user turns off auto-renew (will cancel at period end). */
+    autoRenewing?: boolean;
+    /** Present once canceled (0=user / 1=system / 2=replaced / 3=developer). */
+    cancelReason?: number;
+    /** Set when Google returns an error body (e.g. `{ code: 410 }` for a long-expired token). */
+    error?: {
+        code?: number;
+        message?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Subscription state derived from a Google subscriptions.get response.
+ * - `canceled` — expired and will not renew (autoRenewing=false or a cancelReason) → persist `canceled`.
+ * - `gone` — Google 410 "no longer available" (long-churned) → persist `canceled` (best-effort).
+ * - `active` — a valid (non-expired) subscription → resolve any open failure.
+ * - `unknown` — indeterminate / transient error → no-op.
+ *
+ * @remarks Google's account-hold / grace-period (payment failed but auto-renew still on — the Android
+ * analogue of Apple's `billing_retry`) is currently reported as `active`/`unknown`, not a distinct
+ * "failed" state. If that distinction is needed later, add it to this union in a minor release (adding
+ * a member is semi-breaking for exhaustive `switch` consumers).
+ */
+export type GoogleSubscriptionState = 'canceled' | 'gone' | 'active' | 'unknown';
+/**
+ * Classify a Google subscriptions.get response into a {@link GoogleSubscriptionState}.
+ *
+ * @param purchase - The response body (duck-typed); may be `{ error: { code } }`.
+ * @param now - Current epoch-ms (`Date.now()`); injected for determinism/testing.
+ */
+export declare function classifyGoogleSubscription(purchase: unknown, now: number): {
+    state: GoogleSubscriptionState;
+};
+/** OAuth service-account credentials for the Android Publisher API (per-app; inject, never hardcode in kit). */
+export interface GoogleOAuthCredentials {
+    client_id: string;
+    client_secret: string;
+    refresh_token: string;
+}
+/**
+ * Exchange a refresh token for an Android Publisher access token.
+ *
+ * @param creds - The per-app OAuth credentials.
+ * @param fetchImpl - Injectable fetch (tests).
+ */
+export declare function googleAccessToken(creds: GoogleOAuthCredentials, fetchImpl?: typeof fetch): Promise<string>;
+/**
+ * Fetch a subscription purchase from the Android Publisher API.
+ *
+ * @remarks
+ * Returns the raw JSON (including `{ error: { code } }` bodies for 4xx such as 410) so the caller can
+ * pass it to {@link classifyGoogleSubscription}. `packageName` / `subscriptionId` are per-app.
+ */
+export declare function getGoogleSubscription(opts: {
+    packageName: string;
+    subscriptionId: string;
+    purchaseToken: string;
+    accessToken: string;
+    fetchImpl?: typeof fetch;
+}): Promise<GoogleSubscriptionPurchase>;

package/dist/iap/google.js

@@ -0,0 +1,75 @@
+/**
+ * Google Play (Android Publisher) subscription helpers.
+ *
+ * @remarks
+ * SDK-free and duck-typed like {@link ./apple.ts}. `classifyGoogleSubscription` maps a
+ * `purchases.subscriptions.get` response (or its 410 error) to a state; the consumer persists it
+ * (canceled/gone → `canceled`, active → resolve). `getGoogleSubscription` / `googleAccessToken`
+ * perform the OAuth + Android Publisher calls.
+ */
+const asRecord = (v) => typeof v === 'object' && v !== null ? v : null;
+/**
+ * Classify a Google subscriptions.get response into a {@link GoogleSubscriptionState}.
+ *
+ * @param purchase - The response body (duck-typed); may be `{ error: { code } }`.
+ * @param now - Current epoch-ms (`Date.now()`); injected for determinism/testing.
+ */
+export function classifyGoogleSubscription(purchase, now) {
+    const p = asRecord(purchase);
+    if (!p) {
+        return { state: 'unknown' };
+    }
+    const err = asRecord(p.error);
+    if (err) {
+        // 410 = "The subscription purchase is no longer available for query" (expired too long) = churned.
+        return { state: err.code === 410 ? 'gone' : 'unknown' };
+    }
+    const expiryMs = Number(p.expiryTimeMillis);
+    const isExpired = Number.isFinite(expiryMs) && expiryMs < now;
+    const willNotRenew = p.autoRenewing === false || p.cancelReason !== undefined;
+    if (isExpired && willNotRenew) {
+        return { state: 'canceled' };
+    }
+    if (!isExpired) {
+        return { state: 'active' };
+    }
+    return { state: 'unknown' };
+}
+/**
+ * Exchange a refresh token for an Android Publisher access token.
+ *
+ * @param creds - The per-app OAuth credentials.
+ * @param fetchImpl - Injectable fetch (tests).
+ */
+export async function googleAccessToken(creds, fetchImpl) {
+    const body = new URLSearchParams({
+        client_id: creds.client_id,
+        client_secret: creds.client_secret,
+        grant_type: 'refresh_token',
+        refresh_token: creds.refresh_token,
+    }).toString();
+    const res = (await (fetchImpl ?? fetch)('https://accounts.google.com/o/oauth2/token', {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body,
+    }).then((r) => r.json()));
+    if (!res.access_token) {
+        // 静かに '' を返すと後続が error body → 'unknown' に劣化し、refresh token 失効(invalid_grant)を
+        // 見逃す。呼び出し側に可視化するため throw する。
+        throw new Error('googleAccessToken: no access_token in token response (refresh_token expired?)');
+    }
+    return res.access_token;
+}
+/**
+ * Fetch a subscription purchase from the Android Publisher API.
+ *
+ * @remarks
+ * Returns the raw JSON (including `{ error: { code } }` bodies for 4xx such as 410) so the caller can
+ * pass it to {@link classifyGoogleSubscription}. `packageName` / `subscriptionId` are per-app.
+ */
+export async function getGoogleSubscription(opts) {
+    const url = `https://www.googleapis.com/androidpublisher/v3/applications/${encodeURIComponent(opts.packageName)}` +
+        `/purchases/subscriptions/${encodeURIComponent(opts.subscriptionId)}/tokens/${encodeURIComponent(opts.purchaseToken)}`;
+    // access_token はクエリに載せず Authorization ヘッダで送る（URL ログ/プロキシへの秘匿情報漏洩を防ぐ）。
+    return (opts.fetchImpl ?? fetch)(url, { headers: { authorization: `Bearer ${opts.accessToken}` } }).then((r) => r.json());
+}

package/dist/index.d.ts

@@ -48,7 +48,15 @@ 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 type { StripeFailureReason, PaymentFailureSource, PaymentFailureRecord, PaymentFailureReason, IapFailureReason, 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

@@ -37,6 +37,12 @@ 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,63 @@
+import type { PaymentFailureReason } 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?: PaymentFailureReason | null;
+}): string;
+/**
+ * Build the provider-native `payment_failed.recursions_id`.
+ *
+ * @remarks
+ * - 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: `${orderId}` — Google issues a new orderId per subscription, so it is already cycle-specific.
+ *
+ * Stripe rows use the invoice / subscription id directly (globally unique) and need no helper.
+ *
+ * The provider is stored separately in the `type` column. Provider-native ID formats are disjoint in practice
+ * (Apple numeric pair / Google `GPA.*` / Stripe `in_*` or `sub_*`), so duplicating `type` in the primary-key value
+ * is unnecessary.
+ */
+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];
+    }
+    const stripeReason = input.reason && !('provider' in input.reason) ? input.reason : null;
+    return stripeFailureMessageJa(stripeReason);
+}
+/**
+ * Build the provider-native `payment_failed.recursions_id`.
+ *
+ * @remarks
+ * - 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: `${orderId}` — Google issues a new orderId per subscription, so it is already cycle-specific.
+ *
+ * Stripe rows use the invoice / subscription id directly (globally unique) and need no helper.
+ *
+ * The provider is stored separately in the `type` column. Provider-native ID formats are disjoint in practice
+ * (Apple numeric pair / Google `GPA.*` / Stripe `in_*` or `sub_*`), so duplicating `type` in the primary-key value
+ * is unnecessary.
+ */
+export function iapFailureKey(input) {
+    return input.platform === 'ios' ? `${input.originalTransactionId}:${input.expiresDateMs}` : 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

@@ -22,6 +22,23 @@ export interface StripeFailureReason {
     /** Id of the Subscription the failing invoice belongs to, when resolvable. */
     subscriptionId?: string;
 }
+/** 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). */
+    statusCode?: number;
+    /** Apple auto-renew status (`'0'` means disabled). */
+    autoRenewStatus?: string;
+    /** Apple billing-retry status (`'1'` means retrying a failed renewal). */
+    billingRetryStatus?: string;
+    /** Google cancellation reason code (0=user, 1=system, 2=replaced, 3=developer). */
+    cancelReason?: number;
+}
+/** Provider-specific diagnostic reason stored in `payment_failed.receipt`. */
+export type PaymentFailureReason = StripeFailureReason | IapFailureReason;
 /** Where a {@link PaymentFailureRecord} was captured. */
 export type PaymentFailureSource = 'webhook.invoice.payment_failed' | 'webhook.invoice.payment_action_required' | 'reconcile' | 'checkout' | 'iap';
 /**
@@ -32,7 +49,7 @@ export type PaymentFailureSource = 'webhook.invoice.payment_failed' | 'webhook.i
  * on read via {@link stripeFailureMessageJa} so that wording changes never require a data migration.
  */
 export interface PaymentFailureRecord {
-    reason: StripeFailureReason;
+    reason: PaymentFailureReason;
     source: PaymentFailureSource;
     /** ISO 8601 timestamp of when the failure was captured. */
     occurredAt: string;

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.6",
+  "version": "0.6.9",
   "private": false,
   "publishConfig": {
     "access": "public"