@mathrunet/masamune_cloudflare_purchase_stripe 3.2.0

package/dist/workers/stripe_webhook_secure.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const http_error_1 = require("@mathrunet/masamune_cloudflare/dist/lib/src/http_error");
+require("@mathrunet/masamune");
+const options_1 = require("../lib/options");
+/**
+ * Webhook for proper redirection when 3D Secure authentication is required
+ * (parity with the `stripeWebhookSecure` function of
+ * `@mathrunet/masamune_firebase_purchase_stripe`).
+ * Please set here for `returnUrl`.
+ *
+ * 3Dセキュア認証が必要な場合、適切なリダイレクトを行うためのWebhookです
+ * （`@mathrunet/masamune_firebase_purchase_stripe`の`stripeWebhookSecure`と同等）。
+ * `returnUrl`にこちらを設定してください。
+ *
+ * @param {string} PURCHASE_STRIPE_SECRETKEY
+ * API key (secret key) to connect to Stripe.
+ * Stripeへ接続するためのAPIキー（シークレットキー）。
+ */
+module.exports = (hono, options, data) => {
+    hono.get("/", async (c) => {
+        try {
+            const apiKey = (0, options_1.resolveStripeSecretKey)(c, options);
+            const store = (0, options_1.resolveStripePurchaseStore)(c, options);
+            const stripeClient = (0, options_1.resolveStripeClient)(c, options, apiKey);
+            const token = c.req.query("token");
+            if (!token || typeof token !== "string") {
+                return c.json({
+                    "error": "Invalid parameters",
+                }, 403);
+            }
+            let param;
+            try {
+                param = JSON.parse(await token.decrypt({
+                    key: apiKey.slice(0, 32),
+                    ivKey: apiKey.slice(-16),
+                }));
+            }
+            catch (err) {
+                return c.json({
+                    "error": "Invalid parameters",
+                }, 403);
+            }
+            if (!param["userId"] || !param["orderId"] || !param["successUrl"] || !param["failureUrl"]) {
+                return c.json({
+                    "error": "Invalid parameters",
+                }, 403);
+            }
+            const userId = param["userId"];
+            const orderId = param["orderId"];
+            const successUrl = param["successUrl"];
+            const failureUrl = param["failureUrl"];
+            const purchaseDoc = await store.getPurchase(orderId, userId);
+            // Firebase実装は`paymentId`を参照するが、購入作成時に保存されるキーは
+            // `purchaseId`のためそちらを正とし、`paymentId`はフォールバックに残す。
+            const purchaseId = purchaseDoc?.data["purchaseId"] ?? purchaseDoc?.data["paymentId"];
+            if (!purchaseDoc || !purchaseId) {
+                return c.json({
+                    "error": "The purchase data is not found.",
+                }, 404);
+            }
+            const purchase = await stripeClient.paymentIntents.retrieve(purchaseId);
+            if (!purchase) {
+                return c.json({
+                    "error": "The purchase data is not found.",
+                }, 404);
+            }
+            const status = purchase.status;
+            if (status === "requires_capture" || status === "succeeded" || status === "processing") {
+                return c.redirect(successUrl);
+            }
+            else {
+                return c.redirect(failureUrl);
+            }
+        }
+        catch (err) {
+            return (0, http_error_1.jsonError)(c, err);
+        }
+    });
+    return hono;
+};
+//# sourceMappingURL=stripe_webhook_secure.js.map

package/dist/workers/stripe_webhook_secure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe_webhook_secure.js","sourceRoot":"","sources":["../../src/workers/stripe_webhook_secure.ts"],"names":[],"mappings":"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"}

package/jest.config.json

@@ -0,0 +1,19 @@
+{
+    "moduleNameMapper": {},
+    "moduleDirectories": [
+        "src",
+        "node_modules"
+    ],
+    "moduleFileExtensions": [
+        "js",
+        "ts"
+    ],
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "roots": [
+        "<rootDir>/test"
+    ],
+    "transform": {
+        "^.+\\.(ts|tsx)$": "ts-jest"
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mathrunet/masamune_cloudflare_purchase_stripe",
+  "version": "3.2.0",
+  "description": "Masamune framework plugin package for billing with Stripe on Cloudflare Workers.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "prepublish": "npm install && npm run build && npm run test",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "postversion": "npm run changelog",
+    "changelog": "conventional-changelog -p eslint -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md && git commit -m 'chore(release): publish package'",
+    "publish": "npm publish",
+    "minor_update": "npm version minor",
+    "major_update": "npm version major",
+    "patch_update": "npm version patch"
+  },
+  "engines": {
+    "node": "22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mathrunet/node_masamune.git"
+  },
+  "keywords": [
+    "masamune",
+    "katana",
+    "flutter",
+    "cloudflare",
+    "workers",
+    "stripe"
+  ],
+  "author": "mathru",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mathrunet/node_masamune/issues"
+  },
+  "homepage": "https://github.com/mathrunet/node_masamune#readme",
+  "dependencies": {
+    "@mathrunet/masamune": "^3.10.4",
+    "@mathrunet/masamune_cloudflare": "^3.3.5",
+    "hono": "^4.12.27",
+    "stripe": "^17.6.0",
+    "typescript": "^5.9.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "conventional-changelog-cli": "^5.0.0",
+    "jest": "^30.1.3",
+    "ts-jest": "^29.4.11"
+  }
+}

package/src/functions.ts

@@ -0,0 +1,48 @@
+import { WorkersData } from "@mathrunet/masamune_cloudflare";
+import { StripePurchaseWorkersOptions } from "./lib/options";
+
+/**
+ * Define a list of applicable Functions for CloudflareWorkers.
+ *
+ * Endpoints have parity with `@mathrunet/masamune_firebase_purchase_stripe`:
+ * `stripe` handles mode-based actions (`create_customer_and_payment`,
+ * `create_purchase`, `create_subscription`, etc.) and the webhooks receive
+ * events from Stripe. The metered billing library is provided separately in
+ * `lib/meter`.
+ *
+ * CloudflareWorkers用の適用可能なFunctionの一覧を定義します。
+ *
+ * エンドポイントは`@mathrunet/masamune_firebase_purchase_stripe`と同等です。
+ * `stripe`は`mode`分岐のアクション（`create_customer_and_payment`、
+ * `create_purchase`、`create_subscription`など）を処理し、各WebhookはStripeから
+ * のイベントを受信します。従量課金ライブラリは`lib/meter`で別途提供します。
+ */
+export const Functions = {
+    /**
+     * Performs various Stripe processes (mode-based actions).
+     *
+     * Stripeの各種処理（mode分岐のアクション）を実行します。
+     */
+    stripe: (options: StripePurchaseWorkersOptions = {}) => new WorkersData({ path: "/stripe", func: require("./workers/stripe"), options: options }),
+
+    /**
+     * Receives and processes webhooks from Stripe.
+     *
+     * StripeからのWebhookを受け取り処理を行います。
+     */
+    stripeWebhook: (options: StripePurchaseWorkersOptions = {}) => new WorkersData({ path: "/stripe/webhook", func: require("./workers/stripe_webhook"), options: options }),
+
+    /**
+     * Receives and processes webhooks for Stripe Connect.
+     *
+     * Stripe Connect用のWebhookを受信して処理します。
+     */
+    stripeWebhookConnect: (options: StripePurchaseWorkersOptions = {}) => new WorkersData({ path: "/stripe/webhook/connect", func: require("./workers/stripe_webhook_connect"), options: options }),
+
+    /**
+     * Webhook for proper redirection when 3D Secure authentication is required.
+     *
+     * 3Dセキュア認証が必要な場合、適切なリダイレクトを行うためのWebhookです。
+     */
+    stripeWebhookSecure: (options: StripePurchaseWorkersOptions = {}) => new WorkersData({ path: "/stripe/webhook/secure", func: require("./workers/stripe_webhook_secure"), options: options }),
+} as const;

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2026 mathru. All rights reserved.
+ *
+ * Masamune framework plugin package for billing with Stripe on Cloudflare Workers.
+ *
+ * To use, import * as m from "@mathrunet/masamune_cloudflare_purchase_stripe";
+ *
+ * [mathru.net]: https://mathru.net
+ * [YouTube]: https://www.youtube.com/c/mathrunetchannel
+ */
+export * from "@mathrunet/masamune";
+export * from "@mathrunet/masamune_cloudflare";
+export * from "./functions";
+export * from "./lib/options";
+export * from "./lib/stripe_client";
+export * from "./lib/purchase/interface";
+export * from "./lib/purchase/d1_purchase_store";
+export * from "./lib/purchase/helpers";
+export * from "./lib/purchase/sync_payment";
+export * from "./lib/meter/interface";
+export * from "./lib/meter/stripe_meter_client";
+export * from "./lib/meter/flush_meter";
+export * from "./lib/meter/record_usage";
+export * from "./lib/meter/d1_usage_event_store";
+export * from "./lib/meter/kv_usage_buffer";

package/src/lib/meter/d1_usage_event_store.ts

@@ -0,0 +1,176 @@
+import { StripeUsageEvent, StripeUsageEventStore } from "./interface";
+
+/**
+ * Minimal structural interface for a D1-like SQL database.
+ *
+ * Cloudflare's `D1Database` satisfies this without depending on
+ * `@cloudflare/workers-types`.
+ *
+ * D1相当のSQLデータベースの最小の構造的インターフェース。
+ *
+ * `@cloudflare/workers-types`に依存せずCloudflareの`D1Database`が適合します。
+ */
+export interface SqlDatabaseLike {
+    /**
+     * Prepare a SQL statement.
+     *
+     * SQLステートメントを準備します。
+     */
+    prepare(sql: string): {
+        bind(...args: unknown[]): {
+            run(): Promise<unknown>;
+            all<T = Record<string, unknown>>(): Promise<{ results?: T[] | undefined }>;
+        },
+    };
+}
+
+/**
+ * Column mapping options for [D1UsageEventStore]. Defaults follow the
+ * `usage_events` schema (id / api_key_id / endpoint / units / decision_source /
+ * created_at / flushed_to_stripe).
+ *
+ * [D1UsageEventStore]のカラムマッピングオプション。デフォルトは`usage_events`
+ * スキーマ（id / api_key_id / endpoint / units / decision_source / created_at /
+ * flushed_to_stripe）に従います。
+ */
+export interface D1UsageEventStoreOptions {
+    /**
+     * Table name. Defaults to `usage_events`.
+     *
+     * テーブル名。デフォルトは`usage_events`。
+     */
+    table?: string | undefined;
+
+    /**
+     * Primary key column. Defaults to `id`.
+     *
+     * 主キーのカラム。デフォルトは`id`。
+     */
+    idColumn?: string | undefined;
+
+    /**
+     * Customer key column. Defaults to `api_key_id`.
+     *
+     * 顧客キーのカラム。デフォルトは`api_key_id`。
+     */
+    customerKeyColumn?: string | undefined;
+
+    /**
+     * Endpoint column. Defaults to `endpoint`.
+     *
+     * エンドポイントのカラム。デフォルトは`endpoint`。
+     */
+    endpointColumn?: string | undefined;
+
+    /**
+     * Units column. Defaults to `units`.
+     *
+     * ユニット数のカラム。デフォルトは`units`。
+     */
+    unitsColumn?: string | undefined;
+
+    /**
+     * Source label column. Defaults to `decision_source`.
+     *
+     * ソースラベルのカラム。デフォルトは`decision_source`。
+     */
+    sourceColumn?: string | undefined;
+
+    /**
+     * Creation time column. Defaults to `created_at`.
+     *
+     * 作成時刻のカラム。デフォルトは`created_at`。
+     */
+    createdAtColumn?: string | undefined;
+
+    /**
+     * Flushed flag column (0/1). Defaults to `flushed_to_stripe`.
+     *
+     * 送信済みフラグ（0/1）のカラム。デフォルトは`flushed_to_stripe`。
+     */
+    flushedColumn?: string | undefined;
+}
+
+/**
+ * [StripeUsageEventStore] backed by Cloudflare D1 (or any compatible SQL database).
+ *
+ * Cloudflare D1（または互換SQLデータベース）を用いた[StripeUsageEventStore]。
+ */
+export class D1UsageEventStore implements StripeUsageEventStore {
+    /**
+     * [StripeUsageEventStore] backed by Cloudflare D1 (or any compatible SQL database).
+     *
+     * Cloudflare D1（または互換SQLデータベース）を用いた[StripeUsageEventStore]。
+     */
+    constructor(db: SqlDatabaseLike, options: D1UsageEventStoreOptions = {}) {
+        this._db = db;
+        this._table = options.table ?? "usage_events";
+        this._id = options.idColumn ?? "id";
+        this._customerKey = options.customerKeyColumn ?? "api_key_id";
+        this._endpoint = options.endpointColumn ?? "endpoint";
+        this._units = options.unitsColumn ?? "units";
+        this._source = options.sourceColumn ?? "decision_source";
+        this._createdAt = options.createdAtColumn ?? "created_at";
+        this._flushed = options.flushedColumn ?? "flushed_to_stripe";
+    }
+
+    private readonly _db: SqlDatabaseLike;
+    private readonly _table: string;
+    private readonly _id: string;
+    private readonly _customerKey: string;
+    private readonly _endpoint: string;
+    private readonly _units: string;
+    private readonly _source: string;
+    private readonly _createdAt: string;
+    private readonly _flushed: string;
+
+    /**
+     * Persist a usage event with `flushed = 0`.
+     *
+     * 使用量イベントを未送信状態で永続化します。
+     */
+    async insert(event: StripeUsageEvent): Promise<void> {
+        await this._db
+            .prepare(
+                `INSERT INTO ${this._table}
+                  (${this._id}, ${this._customerKey}, ${this._endpoint}, ${this._units}, ${this._source}, ${this._createdAt}, ${this._flushed})
+                 VALUES (?, ?, ?, ?, ?, ?, 0)`,
+            )
+            .bind(event.id, event.customerKey, event.endpoint, event.units, event.source, event.createdAt)
+            .run();
+    }
+
+    /**
+     * List events not yet flushed to Stripe for the given customer key.
+     *
+     * 指定した顧客キーのStripe未送信イベントを一覧します。
+     */
+    async listPending(customerKey: string): Promise<{ id: string, units: number }[]> {
+        const pending = await this._db
+            .prepare(
+                `SELECT ${this._id} AS id, ${this._units} AS units FROM ${this._table}
+                 WHERE ${this._customerKey} = ? AND ${this._flushed} = 0`,
+            )
+            .bind(customerKey)
+            .all<{ id: string, units: number }>();
+        return pending.results ?? [];
+    }
+
+    /**
+     * Mark the given events as flushed to Stripe.
+     *
+     * 指定したイベントをStripe送信済みとして記録します。
+     */
+    async markFlushed(ids: string[]): Promise<void> {
+        if (ids.length <= 0) {
+            return;
+        }
+        const placeholders = ids.map(() => "?").join(",");
+        await this._db
+            .prepare(
+                `UPDATE ${this._table} SET ${this._flushed} = 1 WHERE ${this._id} IN (${placeholders})`,
+            )
+            .bind(...ids)
+            .run();
+    }
+}

package/src/lib/meter/flush_meter.ts

@@ -0,0 +1,45 @@
+import { StripeUsageEventStore } from "./interface";
+import { StripeMeterClient } from "./stripe_meter_client";
+
+/**
+ * Flush pending usage events for one customer to the Stripe Meter Event API.
+ *
+ * Returns `true` when there was nothing to send or the flush succeeded, and
+ * `false` when Stripe rejected the batch (events stay pending for a retry).
+ *
+ * 顧客1件分の未送信使用量イベントをStripe Meter Event APIへフラッシュします。
+ *
+ * 送信対象がない、または送信に成功した場合は`true`、Stripeがバッチを拒否した
+ * 場合は`false`を返します（イベントは未送信のまま残り、次回再送されます）。
+ */
+export async function flushStripeMeter(options: {
+    store: StripeUsageEventStore,
+    client: StripeMeterClient,
+    customerKey: string,
+    stripeCustomerId: string | null | undefined,
+}): Promise<boolean> {
+    if (!options.client.enabled || !options.stripeCustomerId) {
+        return true;
+    }
+
+    const rows = await options.store.listPending(options.customerKey);
+    const total = rows.reduce((sum, row) => sum + row.units, 0);
+    if (total <= 0) {
+        return true;
+    }
+
+    // 時間窓ベースだと同一窓内の別バッチが Stripe の冪等性で捨てられ過小計上になる。
+    // 送信成功後に flushed を確定するため、identifier はバッチごとに一意でよい。
+    const identifier = `${options.customerKey}:${crypto.randomUUID()}`;
+    const sent = await options.client.sendMeterEvent({
+        stripeCustomerId: options.stripeCustomerId,
+        value: total,
+        identifier: identifier,
+    });
+    if (!sent) {
+        return false;
+    }
+
+    await options.store.markFlushed(rows.map((row) => row.id));
+    return true;
+}

package/src/lib/meter/interface.ts

@@ -0,0 +1,118 @@
+/**
+ * A usage event to be recorded as the source of truth for metered billing.
+ *
+ * 従量課金の正本として記録される使用量イベント。
+ */
+export interface StripeUsageEvent {
+    /**
+     * Unique id of the event.
+     *
+     * イベントの一意なID。
+     */
+    id: string;
+
+    /**
+     * Key identifying the customer on your side (e.g. API key id).
+     *
+     * 自側で顧客を識別するキー（例: APIキーID）。
+     */
+    customerKey: string;
+
+    /**
+     * The endpoint or feature that consumed the units.
+     *
+     * ユニットを消費したエンドポイントや機能。
+     */
+    endpoint: string;
+
+    /**
+     * Number of units consumed.
+     *
+     * 消費ユニット数。
+     */
+    units: number;
+
+    /**
+     * Optional source label of the event.
+     *
+     * イベントのソースラベル（任意）。
+     */
+    source: string | null;
+
+    /**
+     * Creation time in milliseconds since epoch.
+     *
+     * 作成時刻（エポックからのミリ秒）。
+     */
+    createdAt: number;
+}
+
+/**
+ * Storage for usage events. The store is the source of truth for billing.
+ *
+ * 使用量イベントのストレージ。課金の正本となる。
+ */
+export interface StripeUsageEventStore {
+    /**
+     * Persist a usage event with `flushed = false`.
+     *
+     * 使用量イベントを未送信状態で永続化します。
+     */
+    insert(event: StripeUsageEvent): Promise<void>;
+
+    /**
+     * List events not yet flushed to Stripe for the given customer key.
+     *
+     * 指定した顧客キーのStripe未送信イベントを一覧します。
+     */
+    listPending(customerKey: string): Promise<{ id: string, units: number }[]>;
+
+    /**
+     * Mark the given events as flushed to Stripe.
+     *
+     * 指定したイベントをStripe送信済みとして記録します。
+     */
+    markFlushed(ids: string[]): Promise<void>;
+}
+
+/**
+ * State of the flush-trigger buffer for a customer.
+ *
+ * 顧客ごとのフラッシュトリガー用バッファの状態。
+ */
+export interface StripeUsageBufferState {
+    /**
+     * Accumulated units since the last flush.
+     *
+     * 前回フラッシュ以降に積み上がったユニット数。
+     */
+    units: number;
+
+    /**
+     * Time in milliseconds when the buffer window started.
+     *
+     * バッファ窓が開始した時刻（ミリ秒）。
+     */
+    since: number;
+}
+
+/**
+ * Buffer used only to decide when to flush. Billing accuracy does not depend on it.
+ *
+ * フラッシュタイミングの判定のみに使うバッファ。課金精度はこれに依存しない。
+ */
+export interface StripeUsageBuffer {
+    /**
+     * Get the buffer state for the customer key. Returns `null` if absent or corrupt.
+     *
+     * 顧客キーのバッファ状態を取得します。存在しない・壊れている場合は`null`。
+     */
+    get(customerKey: string): Promise<StripeUsageBufferState | null>;
+
+    /**
+     * Store the buffer state for the customer key.
+     *
+     * 顧客キーのバッファ状態を保存します。
+     */
+    put(customerKey: string, value: StripeUsageBufferState, ttlSeconds: number): Promise<void>;
+}

package/src/lib/meter/kv_usage_buffer.ts

@@ -0,0 +1,79 @@
+import { StripeUsageBuffer, StripeUsageBufferState } from "./interface";
+
+/**
+ * Minimal structural interface for a KV-like namespace.
+ *
+ * Cloudflare's `KVNamespace` satisfies this without depending on
+ * `@cloudflare/workers-types`.
+ *
+ * KV相当のネームスペースの最小の構造的インターフェース。
+ *
+ * `@cloudflare/workers-types`に依存せずCloudflareの`KVNamespace`が適合します。
+ */
+export interface KVNamespaceLike {
+    /**
+     * Get a JSON value for the key.
+     *
+     * キーに対応するJSON値を取得します。
+     */
+    get(key: string, type: "json"): Promise<unknown | null>;
+
+    /**
+     * Store a string value for the key.
+     *
+     * キーに対応する文字列値を保存します。
+     */
+    put(
+        key: string,
+        value: string,
+        options?: { expirationTtl?: number | undefined },
+    ): Promise<void>;
+}
+
+/**
+ * [StripeUsageBuffer] backed by Cloudflare KV.
+ *
+ * Cloudflare KVを用いた[StripeUsageBuffer]。
+ */
+export class KVUsageBuffer implements StripeUsageBuffer {
+    /**
+     * [StripeUsageBuffer] backed by Cloudflare KV.
+     *
+     * Cloudflare KVを用いた[StripeUsageBuffer]。
+     */
+    constructor(kv: KVNamespaceLike, options: { prefix?: string | undefined } = {}) {
+        this._kv = kv;
+        this._prefix = options.prefix ?? "usage:";
+    }
+
+    private readonly _kv: KVNamespaceLike;
+    private readonly _prefix: string;
+
+    /**
+     * Get the buffer state for the customer key. Returns `null` if absent or corrupt.
+     *
+     * 顧客キーのバッファ状態を取得します。存在しない・壊れている場合は`null`。
+     */
+    async get(customerKey: string): Promise<StripeUsageBufferState | null> {
+        try {
+            const stored = await this._kv.get(`${this._prefix}${customerKey}`, "json");
+            if (stored && typeof stored === "object") {
+                return stored as StripeUsageBufferState;
+            }
+        } catch {
+            // ignore corrupt buffer
+        }
+        return null;
+    }
+
+    /**
+     * Store the buffer state for the customer key.
+     *
+     * 顧客キーのバッファ状態を保存します。
+     */
+    async put(customerKey: string, value: StripeUsageBufferState, ttlSeconds: number): Promise<void> {
+        await this._kv.put(`${this._prefix}${customerKey}`, JSON.stringify(value), {
+            expirationTtl: ttlSeconds,
+        });
+    }
+}