@mathrunet/masamune_cloudflare_purchase_stripe 3.2.0

package/src/lib/purchase/d1_purchase_store.ts

@@ -0,0 +1,268 @@
+import { SqlDatabaseLike } from "../meter/d1_usage_event_store";
+import {
+    mergeDocumentData,
+    StripeDocumentData,
+    StripePaymentDocument,
+    StripePurchaseDocument,
+    StripePurchaseStore,
+    StripeUserDocument,
+} from "./interface";
+
+/**
+ * Table name options for [D1StripePurchaseStore].
+ *
+ * Expected default schema (see the package README for the full DDL):
+ *
+ * - `stripe_users(user_id PK, customer_id, account_id, data, created_at, updated_at)`
+ * - `stripe_payments(user_id, payment_id, data, created_at, updated_at, PK(user_id, payment_id))`
+ * - `stripe_purchases(order_id PK, user_id, purchase_id, subscription_id, data, created_at, updated_at)`
+ *
+ * [D1StripePurchaseStore]のテーブル名オプション。
+ *
+ * 想定するデフォルトスキーマ（完全なDDLはパッケージREADMEを参照）:
+ *
+ * - `stripe_users(user_id PK, customer_id, account_id, data, created_at, updated_at)`
+ * - `stripe_payments(user_id, payment_id, data, created_at, updated_at, PK(user_id, payment_id))`
+ * - `stripe_purchases(order_id PK, user_id, purchase_id, subscription_id, data, created_at, updated_at)`
+ */
+export interface D1StripePurchaseStoreOptions {
+    /**
+     * Users table name. Defaults to `stripe_users`.
+     *
+     * ユーザーテーブル名。デフォルトは`stripe_users`。
+     */
+    usersTable?: string | undefined;
+
+    /**
+     * Payments table name. Defaults to `stripe_payments`.
+     *
+     * 支払い方法テーブル名。デフォルトは`stripe_payments`。
+     */
+    paymentsTable?: string | undefined;
+
+    /**
+     * Purchases table name. Defaults to `stripe_purchases`.
+     *
+     * 購入テーブル名。デフォルトは`stripe_purchases`。
+     */
+    purchasesTable?: string | undefined;
+}
+
+interface DocumentRow {
+    data: string | null;
+    user_id?: string | null;
+}
+
+/**
+ * [StripePurchaseStore] backed by Cloudflare D1 (or any compatible SQL database).
+ *
+ * Documents are stored as JSON in the `data` column while lookup keys
+ * (`customer_id` / `account_id` / `purchase_id` / `subscription_id`) are kept in
+ * sync as indexed columns.
+ *
+ * Cloudflare D1（または互換SQLデータベース）を用いた[StripePurchaseStore]。
+ *
+ * ドキュメントは`data`カラムへJSONとして保存し、検索キー
+ * （`customer_id` / `account_id` / `purchase_id` / `subscription_id`）は
+ * インデックス付きカラムとして同期します。
+ */
+export class D1StripePurchaseStore implements StripePurchaseStore {
+    /**
+     * [StripePurchaseStore] backed by Cloudflare D1 (or any compatible SQL database).
+     *
+     * Cloudflare D1（または互換SQLデータベース）を用いた[StripePurchaseStore]。
+     */
+    constructor(db: SqlDatabaseLike, options: D1StripePurchaseStoreOptions = {}) {
+        this._db = db;
+        this._users = options.usersTable ?? "stripe_users";
+        this._payments = options.paymentsTable ?? "stripe_payments";
+        this._purchases = options.purchasesTable ?? "stripe_purchases";
+    }
+
+    private readonly _db: SqlDatabaseLike;
+    private readonly _users: string;
+    private readonly _payments: string;
+    private readonly _purchases: string;
+
+    private static _parse(row: DocumentRow | undefined): StripeDocumentData | null {
+        if (!row) {
+            return null;
+        }
+        try {
+            return JSON.parse(row.data ?? "{}") as StripeDocumentData;
+        } catch {
+            return {};
+        }
+    }
+
+    async getUser(userId: string): Promise<StripeUserDocument | null> {
+        const res = await this._db
+            .prepare(`SELECT data FROM ${this._users} WHERE user_id = ?`)
+            .bind(userId)
+            .all<DocumentRow>();
+        const data = D1StripePurchaseStore._parse(res.results?.[0]);
+        return data === null ? null : { userId, data };
+    }
+
+    async findUserByCustomerId(customerId: string): Promise<StripeUserDocument | null> {
+        const res = await this._db
+            .prepare(`SELECT user_id, data FROM ${this._users} WHERE customer_id = ? LIMIT 1`)
+            .bind(customerId)
+            .all<DocumentRow & { user_id: string }>();
+        const row = res.results?.[0];
+        const data = D1StripePurchaseStore._parse(row);
+        return row && data !== null ? { userId: row.user_id, data } : null;
+    }
+
+    async findUserByAccountId(accountId: string): Promise<StripeUserDocument | null> {
+        const res = await this._db
+            .prepare(`SELECT user_id, data FROM ${this._users} WHERE account_id = ? LIMIT 1`)
+            .bind(accountId)
+            .all<DocumentRow & { user_id: string }>();
+        const row = res.results?.[0];
+        const data = D1StripePurchaseStore._parse(row);
+        return row && data !== null ? { userId: row.user_id, data } : null;
+    }
+
+    async saveUser(userId: string, update: StripeDocumentData): Promise<void> {
+        const now = Date.now();
+        const existing = await this.getUser(userId);
+        const merged = mergeDocumentData(existing?.data ?? {}, update);
+        const customerId = typeof merged["customer"] === "string" ? merged["customer"] : null;
+        const accountId = typeof merged["account"] === "string" ? merged["account"] : null;
+        if (existing) {
+            await this._db
+                .prepare(
+                    `UPDATE ${this._users}
+                     SET customer_id = ?, account_id = ?, data = ?, updated_at = ?
+                     WHERE user_id = ?`,
+                )
+                .bind(customerId, accountId, JSON.stringify(merged), now, userId)
+                .run();
+        } else {
+            await this._db
+                .prepare(
+                    `INSERT INTO ${this._users}
+                      (user_id, customer_id, account_id, data, created_at, updated_at)
+                     VALUES (?, ?, ?, ?, ?, ?)`,
+                )
+                .bind(userId, customerId, accountId, JSON.stringify(merged), now, now)
+                .run();
+        }
+    }
+
+    async listPayments(userId: string): Promise<StripePaymentDocument[]> {
+        const res = await this._db
+            .prepare(`SELECT payment_id, data FROM ${this._payments} WHERE user_id = ?`)
+            .bind(userId)
+            .all<{ payment_id: string, data: string | null }>();
+        return (res.results ?? []).map((row) => ({
+            userId,
+            paymentId: row.payment_id,
+            data: D1StripePurchaseStore._parse(row) ?? {},
+        }));
+    }
+
+    async savePayment(userId: string, paymentId: string, update: StripeDocumentData): Promise<void> {
+        const now = Date.now();
+        const res = await this._db
+            .prepare(`SELECT data FROM ${this._payments} WHERE user_id = ? AND payment_id = ?`)
+            .bind(userId, paymentId)
+            .all<DocumentRow>();
+        const existing = D1StripePurchaseStore._parse(res.results?.[0]);
+        const merged = mergeDocumentData(existing ?? {}, update);
+        if (existing !== null) {
+            await this._db
+                .prepare(
+                    `UPDATE ${this._payments} SET data = ?, updated_at = ?
+                     WHERE user_id = ? AND payment_id = ?`,
+                )
+                .bind(JSON.stringify(merged), now, userId, paymentId)
+                .run();
+        } else {
+            await this._db
+                .prepare(
+                    `INSERT INTO ${this._payments}
+                      (user_id, payment_id, data, created_at, updated_at)
+                     VALUES (?, ?, ?, ?, ?)`,
+                )
+                .bind(userId, paymentId, JSON.stringify(merged), now, now)
+                .run();
+        }
+    }
+
+    async deletePayment(userId: string, paymentId: string): Promise<void> {
+        await this._db
+            .prepare(`DELETE FROM ${this._payments} WHERE user_id = ? AND payment_id = ?`)
+            .bind(userId, paymentId)
+            .run();
+    }
+
+    async getPurchase(orderId: string, userId?: string | undefined): Promise<StripePurchaseDocument | null> {
+        const res = userId
+            ? await this._db
+                .prepare(`SELECT user_id, data FROM ${this._purchases} WHERE order_id = ? AND user_id = ?`)
+                .bind(orderId, userId)
+                .all<DocumentRow>()
+            : await this._db
+                .prepare(`SELECT user_id, data FROM ${this._purchases} WHERE order_id = ?`)
+                .bind(orderId)
+                .all<DocumentRow>();
+        const row = res.results?.[0];
+        const data = D1StripePurchaseStore._parse(row);
+        return row && data !== null ? { orderId, userId: row.user_id ?? null, data } : null;
+    }
+
+    async findPurchaseByPurchaseId(purchaseId: string): Promise<StripePurchaseDocument | null> {
+        const res = await this._db
+            .prepare(`SELECT order_id, user_id, data FROM ${this._purchases} WHERE purchase_id = ? LIMIT 1`)
+            .bind(purchaseId)
+            .all<DocumentRow & { order_id: string }>();
+        const row = res.results?.[0];
+        const data = D1StripePurchaseStore._parse(row);
+        return row && data !== null ? { orderId: row.order_id, userId: row.user_id ?? null, data } : null;
+    }
+
+    async findPurchaseBySubscriptionId(subscriptionId: string): Promise<StripePurchaseDocument | null> {
+        const res = await this._db
+            .prepare(`SELECT order_id, user_id, data FROM ${this._purchases} WHERE subscription_id = ? LIMIT 1`)
+            .bind(subscriptionId)
+            .all<DocumentRow & { order_id: string }>();
+        const row = res.results?.[0];
+        const data = D1StripePurchaseStore._parse(row);
+        return row && data !== null ? { orderId: row.order_id, userId: row.user_id ?? null, data } : null;
+    }
+
+    async savePurchase(
+        orderId: string,
+        update: StripeDocumentData,
+        options: { userId?: string | undefined } = {},
+    ): Promise<void> {
+        const now = Date.now();
+        const existing = await this.getPurchase(orderId);
+        const merged = mergeDocumentData(existing?.data ?? {}, update);
+        const userId = options.userId
+            ?? (typeof merged["user"] === "string" ? merged["user"] : existing?.userId ?? null);
+        const purchaseId = typeof merged["purchaseId"] === "string" ? merged["purchaseId"] : null;
+        const subscriptionId = typeof merged["subscription"] === "string" ? merged["subscription"] : null;
+        if (existing) {
+            await this._db
+                .prepare(
+                    `UPDATE ${this._purchases}
+                     SET user_id = ?, purchase_id = ?, subscription_id = ?, data = ?, updated_at = ?
+                     WHERE order_id = ?`,
+                )
+                .bind(userId, purchaseId, subscriptionId, JSON.stringify(merged), now, orderId)
+                .run();
+        } else {
+            await this._db
+                .prepare(
+                    `INSERT INTO ${this._purchases}
+                      (order_id, user_id, purchase_id, subscription_id, data, created_at, updated_at)
+                     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+                )
+                .bind(orderId, userId, purchaseId, subscriptionId, JSON.stringify(merged), now, now)
+                .run();
+        }
+    }
+}

package/src/lib/purchase/helpers.ts

@@ -0,0 +1,77 @@
+import Stripe from "stripe";
+import { Context } from "hono";
+import { HttpError } from "@mathrunet/masamune_cloudflare/dist/lib/src/http_error";
+import { StripePurchaseWorkersOptions } from "../options";
+import { StripePurchaseStore, StripeUserDocument } from "./interface";
+
+/**
+ * Resolve the default payment method of a user, following the same fallback
+ * chain as the Firebase implementation: stored `defaultPayment` -> customer's
+ * `invoice_settings.default_payment_method` -> first stored payment method.
+ * The resolved value is saved back to the user document.
+ *
+ * Firebase実装と同じフォールバック連鎖でユーザーのデフォルト支払い方法を
+ * 解決します: 保存済み`defaultPayment` → カスタマーの
+ * `invoice_settings.default_payment_method` → 保存済み支払い方法の先頭。
+ * 解決した値はユーザードキュメントへ書き戻します。
+ */
+export async function resolveDefaultPayment(options: {
+    stripeClient: Stripe,
+    store: StripePurchaseStore,
+    user: StripeUserDocument,
+}): Promise<string> {
+    const { stripeClient, store, user } = options;
+    let defaultPayment = user.data["defaultPayment"] as string | undefined;
+    if (defaultPayment) {
+        return defaultPayment;
+    }
+    const customer = await stripeClient.customers.retrieve(
+        user.data["customer"],
+    ) as Stripe.Customer;
+    defaultPayment = (customer.invoice_settings.default_payment_method ?? undefined) as string | undefined;
+    if (!defaultPayment) {
+        const payments = await store.listPayments(user.userId);
+        if (payments.length <= 0) {
+            throw new HttpError(404, "The payment method is not found.");
+        }
+        defaultPayment = payments[0]?.data["id"] as string | undefined;
+        if (!defaultPayment) {
+            throw new HttpError(404, "The payment method is not found.");
+        }
+    }
+    await store.saveUser(user.userId, { defaultPayment });
+    return defaultPayment;
+}
+
+/**
+ * Resolve the email address of a user (parity with `admin.auth().getUser()` in
+ * the Firebase implementation): `options.resolveUserEmail` -> `email` field of
+ * the user document -> billing details of the default payment method.
+ *
+ * ユーザーのメールアドレスを解決します（Firebase実装の
+ * `admin.auth().getUser()`相当）: `options.resolveUserEmail` → ユーザー
+ * ドキュメントの`email`フィールド → デフォルト支払い方法のbilling details。
+ */
+export async function resolveUserEmail(options: {
+    context: Context,
+    workersOptions: StripePurchaseWorkersOptions,
+    stripeClient: Stripe,
+    user: StripeUserDocument,
+    defaultPayment?: string | undefined,
+}): Promise<string> {
+    const { context, workersOptions, stripeClient, user, defaultPayment } = options;
+    let email = workersOptions.resolveUserEmail
+        ? await workersOptions.resolveUserEmail(context, user.userId)
+        : undefined;
+    if (!email && typeof user.data["email"] === "string") {
+        email = user.data["email"];
+    }
+    if (!email && defaultPayment) {
+        const paymentMethod = await stripeClient.paymentMethods.retrieve(defaultPayment);
+        email = paymentMethod?.billing_details?.email ?? undefined;
+    }
+    if (!email) {
+        throw new HttpError(404, "The user's email is not found.");
+    }
+    return email;
+}

package/src/lib/purchase/interface.ts

@@ -0,0 +1,215 @@
+/**
+ * Free-form document data stored for Stripe users / payments / purchases.
+ *
+ * Mirrors the Firestore document model of
+ * `@mathrunet/masamune_firebase_purchase_stripe`. Setting a key to `null` in an
+ * update deletes the key (equivalent to `FieldValue.delete()`).
+ *
+ * Stripeのユーザー・支払い方法・購入情報として保存する自由形式のドキュメントデータ。
+ *
+ * `@mathrunet/masamune_firebase_purchase_stripe`のFirestoreドキュメントモデルを
+ * 踏襲します。更新時にキーへ`null`を設定するとそのキーを削除します
+ * （`FieldValue.delete()`相当）。
+ */
+export type StripeDocumentData = { [key: string]: any };
+
+/**
+ * Stored Stripe user (customer / connect account) document.
+ *
+ * 保存されたStripeユーザー（カスタマー / Connectアカウント）ドキュメント。
+ */
+export interface StripeUserDocument {
+    /**
+     * Application user ID.
+     *
+     * アプリケーションのユーザーID。
+     */
+    userId: string;
+
+    /**
+     * Document data (`customer`, `account`, `defaultPayment`, etc.).
+     *
+     * ドキュメントデータ（`customer`、`account`、`defaultPayment`など）。
+     */
+    data: StripeDocumentData;
+}
+
+/**
+ * Stored Stripe payment method document.
+ *
+ * 保存されたStripe支払い方法ドキュメント。
+ */
+export interface StripePaymentDocument {
+    /**
+     * Application user ID.
+     *
+     * アプリケーションのユーザーID。
+     */
+    userId: string;
+
+    /**
+     * Stripe payment method ID.
+     *
+     * Stripeの支払い方法ID。
+     */
+    paymentId: string;
+
+    /**
+     * Document data (`type`, `brand`, `numberLast`, `default`, etc.).
+     *
+     * ドキュメントデータ（`type`、`brand`、`numberLast`、`default`など）。
+     */
+    data: StripeDocumentData;
+}
+
+/**
+ * Stored Stripe purchase / subscription document.
+ *
+ * 保存されたStripe購入・サブスクリプションドキュメント。
+ */
+export interface StripePurchaseDocument {
+    /**
+     * Order ID (database key).
+     *
+     * 注文ID（データベースのキー）。
+     */
+    orderId: string;
+
+    /**
+     * Application user ID. May be `null` for subscription records created from
+     * webhooks before the user is known.
+     *
+     * アプリケーションのユーザーID。ユーザーが未確定のWebhook起点の
+     * サブスクリプションレコードでは`null`になることがあります。
+     */
+    userId: string | null;
+
+    /**
+     * Document data (`purchaseId`, `subscription`, `confirm`, `success`, etc.).
+     *
+     * ドキュメントデータ（`purchaseId`、`subscription`、`confirm`、`success`など）。
+     */
+    data: StripeDocumentData;
+}
+
+/**
+ * Persistence boundary for Stripe purchase data.
+ *
+ * Replaces the Firestore paths (`PURCHASE_STRIPE_USERPATH` /
+ * `PURCHASE_STRIPE_PAYMENTPATH` / `PURCHASE_STRIPE_PURCHASEPATH`) of the
+ * Firebase implementation. All `save*` methods merge the update into the
+ * existing document; keys set to `null` are removed.
+ *
+ * Stripe購入データの永続化境界。
+ *
+ * Firebase実装のFirestoreパス（`PURCHASE_STRIPE_USERPATH` /
+ * `PURCHASE_STRIPE_PAYMENTPATH` / `PURCHASE_STRIPE_PURCHASEPATH`）を置き換えます。
+ * すべての`save*`メソッドは既存ドキュメントへ更新をマージし、`null`が設定された
+ * キーは削除されます。
+ */
+export interface StripePurchaseStore {
+    /**
+     * Get a user document by application user ID.
+     *
+     * アプリケーションのユーザーIDでユーザードキュメントを取得します。
+     */
+    getUser(userId: string): Promise<StripeUserDocument | null>;
+
+    /**
+     * Find a user document by Stripe customer ID.
+     *
+     * StripeのカスタマーIDでユーザードキュメントを検索します。
+     */
+    findUserByCustomerId(customerId: string): Promise<StripeUserDocument | null>;
+
+    /**
+     * Find a user document by Stripe connect account ID.
+     *
+     * StripeのConnectアカウントIDでユーザードキュメントを検索します。
+     */
+    findUserByAccountId(accountId: string): Promise<StripeUserDocument | null>;
+
+    /**
+     * Merge-save a user document.
+     *
+     * ユーザードキュメントをマージ保存します。
+     */
+    saveUser(userId: string, update: StripeDocumentData): Promise<void>;
+
+    /**
+     * List payment method documents of a user.
+     *
+     * ユーザーの支払い方法ドキュメントを一覧します。
+     */
+    listPayments(userId: string): Promise<StripePaymentDocument[]>;
+
+    /**
+     * Merge-save a payment method document.
+     *
+     * 支払い方法ドキュメントをマージ保存します。
+     */
+    savePayment(userId: string, paymentId: string, update: StripeDocumentData): Promise<void>;
+
+    /**
+     * Delete a payment method document.
+     *
+     * 支払い方法ドキュメントを削除します。
+     */
+    deletePayment(userId: string, paymentId: string): Promise<void>;
+
+    /**
+     * Get a purchase document by order ID. When `userId` is given the document
+     * must belong to that user.
+     *
+     * 注文IDで購入ドキュメントを取得します。`userId`を指定した場合はその
+     * ユーザーの所有ドキュメントに限定します。
+     */
+    getPurchase(orderId: string, userId?: string | undefined): Promise<StripePurchaseDocument | null>;
+
+    /**
+     * Find a purchase document by Stripe payment intent ID.
+     *
+     * StripeのPaymentIntent IDで購入ドキュメントを検索します。
+     */
+    findPurchaseByPurchaseId(purchaseId: string): Promise<StripePurchaseDocument | null>;
+
+    /**
+     * Find a purchase document by Stripe subscription ID.
+     *
+     * StripeのサブスクリプションIDで購入ドキュメントを検索します。
+     */
+    findPurchaseBySubscriptionId(subscriptionId: string): Promise<StripePurchaseDocument | null>;
+
+    /**
+     * Merge-save a purchase document.
+     *
+     * 購入ドキュメントをマージ保存します。
+     */
+    savePurchase(orderId: string, update: StripeDocumentData, options?: { userId?: string | undefined }): Promise<void>;
+}
+
+/**
+ * Apply a merge update to document data. Keys set to `null` are removed
+ * (equivalent to `FieldValue.delete()`), `undefined` keys are ignored.
+ *
+ * ドキュメントデータへマージ更新を適用します。`null`が設定されたキーは削除され
+ * （`FieldValue.delete()`相当）、`undefined`のキーは無視されます。
+ */
+export function mergeDocumentData(
+    current: StripeDocumentData,
+    update: StripeDocumentData,
+): StripeDocumentData {
+    const merged: StripeDocumentData = { ...current };
+    for (const key of Object.keys(update)) {
+        const value = update[key];
+        if (value === undefined) {
+            continue;
+        }
+        if (value === null) {
+            delete merged[key];
+        } else {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}

package/src/lib/purchase/sync_payment.ts

@@ -0,0 +1,95 @@
+import Stripe from "stripe";
+import { StripePurchaseStore } from "./interface";
+
+/**
+ * Synchronize the payment methods of a Stripe customer into the store
+ * (parity with `syncStripePayment` in the Firebase implementation).
+ *
+ * Stripeカスタマーの支払い方法をストアへ同期します
+ * （Firebase実装の`syncStripePayment`相当）。
+ */
+export async function syncStripePayment(options: {
+    stripeClient: Stripe,
+    store: StripePurchaseStore,
+    userId: string,
+    customerId: string,
+}): Promise<void> {
+    const { stripeClient, store, userId, customerId } = options;
+    const customer = await stripeClient.customers.retrieve(
+        customerId,
+    ) as Stripe.Customer;
+    let defaultSource = customer.invoice_settings.default_payment_method as string | null;
+    const paymentMethods = await stripeClient.customers.listPaymentMethods(
+        customerId,
+        {
+            type: "card",
+        },
+    );
+
+    if (!defaultSource && paymentMethods.data.length > 0) {
+        defaultSource = paymentMethods.data[0]?.id ?? null;
+        if (defaultSource) {
+            await stripeClient.customers.update(
+                customerId,
+                {
+                    invoice_settings: {
+                        default_payment_method: defaultSource,
+                    },
+                },
+            );
+        }
+    }
+
+    const payments = await store.listPayments(userId);
+
+    for (const payment of payments) {
+        const method = paymentMethods.data.find((m) => m.id == payment.data["id"]);
+        if (!method) {
+            await store.deletePayment(userId, payment.paymentId);
+            continue;
+        }
+        const card = method.card;
+        if (!card) {
+            continue;
+        }
+        const isDefault = method.id == defaultSource;
+        if (method.type === payment.data["type"] && card.exp_month === payment.data["expMonth"] && card.exp_year === payment.data["expYear"] && card.brand === payment.data["brand"] && card.last4 === payment.data["numberLast"] && isDefault === payment.data["default"]) {
+            continue;
+        }
+        await store.savePayment(userId, payment.paymentId, {
+            type: method.type,
+            expMonth: card.exp_month,
+            expYear: card.exp_year,
+            brand: card.brand,
+            numberLast: card.last4,
+            default: isDefault,
+        });
+    }
+    for (const method of paymentMethods.data) {
+        const card = method.card;
+        if (!card) {
+            continue;
+        }
+        const existing = payments.find((item) => item.data["id"] == method.id);
+        if (existing) {
+            continue;
+        }
+        const uid = method.id;
+        const isDefault = method.id == defaultSource;
+        await store.savePayment(userId, uid, {
+            "@uid": uid,
+            "@time": new Date(),
+            id: uid,
+            type: method.type,
+            expMonth: card.exp_month,
+            expYear: card.exp_year,
+            brand: card.brand,
+            numberLast: card.last4,
+            default: isDefault,
+        });
+    }
+
+    await store.saveUser(userId, {
+        defaultPayment: defaultSource ?? null,
+    });
+}