@rdlabo/workers-hono-kit 0.6.4 → 0.6.8

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/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/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());
+}