@mathrunet/masamune_cloudflare_purchase_stripe 3.2.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 3.0.0
+
+ - **FEAT**(masamune_cloudflare_purchase_stripe): initial release with Stripe Meter (metered billing) library for Cloudflare Workers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mathru (https://mathru.net)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+<p align="center">
+  <a href="https://mathru.net">
+    <img width="240px" src="https://raw.githubusercontent.com/mathrunet/node_masamune/main/.github/images/icon.png" alt="Masamune logo" style="border-radius: 32px"><br/>
+  </a>
+  <h1 align="center">Stripe for Cloudflare Workers</h1>
+</p>
+
+<p align="center">
+  <a href="https://github.com/mathrunet">
+    <img src="https://img.shields.io/static/v1?label=GitHub&message=Follow&logo=GitHub&color=333333&link=https://github.com/mathrunet" alt="Follow on GitHub" />
+  </a>
+  <a href="https://x.com/mathru">
+    <img src="https://img.shields.io/static/v1?label=@mathru&message=Follow&logo=X&color=0F1419&link=https://x.com/mathru" alt="Follow on X" />
+  </a>
+  <a href="https://www.youtube.com/c/mathrunetchannel">
+    <img src="https://img.shields.io/static/v1?label=YouTube&message=Follow&logo=YouTube&color=FF0000&link=https://www.youtube.com/c/mathrunetchannel" alt="Follow on YouTube" />
+  </a>
+  <a href="https://github.com/invertase/melos">
+    <img src="https://img.shields.io/static/v1?label=maintained%20with&message=melos&color=FF1493&link=https://github.com/invertase/melos" alt="Maintained with Melos" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/sponsors/mathrunet"><img src="https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=ff69b4&link=https://github.com/sponsors/mathrunet" alt="GitHub Sponsor" /></a>
+</p>
+
+---
+
+[[GitHub]](https://github.com/mathrunet) | [[YouTube]](https://www.youtube.com/c/mathrunetchannel) | [[Packages]](https://pub.dev/publishers/mathru.net/packages) | [[X]](https://x.com/mathru) | [[LinkedIn]](https://www.linkedin.com/in/mathrunet/) | [[mathru.net]](https://mathru.net)
+
+---
+
+Masamune framework plugin package for billing with Stripe on Cloudflare Workers.
+
+# Installation
+
+Install the following package:
+
+```bash
+npm install @mathrunet/masamune_cloudflare_purchase_stripe
+```
+
+# Implementation
+
+## Features
+
+Provides payment actions equivalent to `@mathrunet/masamune_firebase_purchase_stripe` and a Stripe Meter library for usage-based billing. All operations use the `stripe` SDK configured for Workers with `createFetchHttpClient`.
+
+### Payment Endpoints (Functions)
+
+- `stripe` — payment actions selected by `mode` (POST with a JSON body)
+  - Connect: `create_account` / `delete_account` / `get_account` / `dashboard_account`
+  - Customers and payment methods: `create_customer_and_payment` / `set_customer_default_payment` / `delete_payment` / `delete_customer`
+  - Authorization: `authorization` / `confirm_authorization`
+  - Payments: `create_purchase` / `confirm_purchase` / `capture_purchase` / `refresh_purchase` / `cancel_purchase` / `refund_purchase`
+  - Subscriptions: `create_subscription` / `delete_subscription`
+- `stripeWebhook` — receives Stripe webhooks (signature verification required). Processes PaymentIntent, payment method, customer, Checkout, and subscription events (creation/update/trial end/deletion) and synchronizes them to the store.
+- `stripeWebhookConnect` — Stripe Connect webhook (`account.updated`)
+- `stripeWebhookSecure` — redirect webhook after 3D Secure authentication
+
+Data is stored through `StripePurchaseStore` instead of Firestore. The default is D1's `D1StripePurchaseStore` (`stripe_users` / `stripe_payments` / `stripe_purchases`). Table names are configurable, and custom storage can be substituted by implementing `StripePurchaseStore`.
+
+```typescript
+import { Hono } from "hono";
+import { Functions } from "@mathrunet/masamune_cloudflare_purchase_stripe";
+
+const app = new Hono();
+app.route("/stripe/webhook", Functions.stripeWebhook().build());
+app.route("/stripe", Functions.stripe().build());
+```
+
+To keep Worker bundles small, import builders directly from the `dist/purchase` entry point (root imports include re-exports of the entire Masamune framework).
+
+```typescript
+import { Hono } from "hono";
+import {
+  buildStripeWebhook,
+  D1StripePurchaseStore,
+} from "@mathrunet/masamune_cloudflare_purchase_stripe/dist/purchase";
+
+const app = buildStripeWebhook(new Hono(), {
+  secretKey: env.STRIPE_SECRET_KEY,
+  webhookSecret: env.STRIPE_WEBHOOK_SECRET,
+  store: () => new D1StripePurchaseStore(env.DB),
+}, {});
+```
+
+### D1 Schema (Default)
+
+```sql
+CREATE TABLE stripe_users (
+  user_id TEXT PRIMARY KEY,
+  customer_id TEXT,
+  account_id TEXT,
+  data TEXT NOT NULL DEFAULT '{}',
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE INDEX idx_stripe_users_customer ON stripe_users(customer_id);
+CREATE INDEX idx_stripe_users_account ON stripe_users(account_id);
+
+CREATE TABLE stripe_payments (
+  user_id TEXT NOT NULL,
+  payment_id TEXT NOT NULL,
+  data TEXT NOT NULL DEFAULT '{}',
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (user_id, payment_id)
+);
+
+CREATE TABLE stripe_purchases (
+  order_id TEXT PRIMARY KEY,
+  user_id TEXT,
+  purchase_id TEXT,
+  subscription_id TEXT,
+  data TEXT NOT NULL DEFAULT '{}',
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE INDEX idx_stripe_purchases_user ON stripe_purchases(user_id);
+CREATE INDEX idx_stripe_purchases_purchase ON stripe_purchases(purchase_id);
+CREATE INDEX idx_stripe_purchases_subscription ON stripe_purchases(subscription_id);
+```
+
+### Stripe Meter Library (Usage-Based Billing)
+
+- `recordUsage` — records usage events. Inserts them into D1 (the source of truth) and flushes to Stripe when the KV buffer is full (default 10 units) or the time threshold is reached (default 60 seconds).
+- `flushStripeMeter` — aggregates unsent events by customer and sends batches to the Stripe Meter Event API (`/v1/billing/meter_events`, basil or later). Each batch uses a unique identifier for idempotency. Failed events remain unsent and are retried on the next run.
+- `D1UsageEventStore` / `KVUsageBuffer` — bundled D1 and KV adapters. Table names, column names, and key prefixes are configurable. Substitute custom storage by implementing `StripeUsageEventStore` / `StripeUsageBuffer`.
+- `StripeMeterClient` — uses the `stripe` SDK with a fetch HTTP client. Tests can inject `fetch` or `stripeClient` stubs.
+
+To keep Worker bundles small when using only the Meter library, import from the `dist/meter` entry point (root imports include re-exports of the entire Masamune framework).
+
+```typescript
+import {
+  D1UsageEventStore,
+  KVUsageBuffer,
+  StripeMeterClient,
+  recordUsage,
+} from "@mathrunet/masamune_cloudflare_purchase_stripe/dist/meter";
+
+// For example, at the end of request handling (waitUntil recommended)
+await recordUsage({
+  store: new D1UsageEventStore(env.DB),
+  buffer: new KVUsageBuffer(env.USAGE_BUFFER),
+  client: new StripeMeterClient({
+    secretKey: env.PURCHASE_STRIPE_SECRETKEY,
+    eventName: env.PURCHASE_STRIPE_METER_EVENT_NAME ?? "my_meter",
+  }),
+  customerKey: apiKey.id,
+  stripeCustomerId: apiKey.stripe_customer_id,
+  endpoint: "decide",
+  units: 1,
+});
+```
+
+If the secret key or the customer's Stripe customer ID is missing, sending is skipped and usage is recorded only in D1.
+
+## Environment Variables
+
+- `PURCHASE_STRIPE_SECRETKEY` — Stripe secret key (Worker secret)
+- `PURCHASE_STRIPE_METER_EVENT_NAME` — Stripe Meter event name
+- `PURCHASE_STRIPE_WEBHOOKSECRET` — signing secret for the main webhook (Worker secret)
+- `PURCHASE_STRIPE_WEBHOOKCONNECTSECRET` — signing secret for the Connect webhook (Worker secret)
+- `PURCHASE_STRIPE_EMAILPROVIDER` — 3D Secure email provider (default `sendgrid`)
+- `MAIL_SENDGRID_APIKEY` — SendGrid API key (required only for 3D Secure email; Worker secret)
+
+The Firebase implementation's email lookup through `admin.auth()` is replaced by an injected `options.resolveUserEmail`, the user document's `email` field, or the default payment method's billing details.
+
+# GitHub Sponsors
+
+Sponsors are always welcome. Thank you for your support!
+
+[https://github.com/sponsors/mathrunet](https://github.com/sponsors/mathrunet)

package/dist/functions.d.ts

@@ -0,0 +1,44 @@
+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 declare const Functions: {
+    /**
+     * Performs various Stripe processes (mode-based actions).
+     *
+     * Stripeの各種処理（mode分岐のアクション）を実行します。
+     */
+    readonly stripe: (options?: StripePurchaseWorkersOptions) => WorkersData;
+    /**
+     * Receives and processes webhooks from Stripe.
+     *
+     * StripeからのWebhookを受け取り処理を行います。
+     */
+    readonly stripeWebhook: (options?: StripePurchaseWorkersOptions) => WorkersData;
+    /**
+     * Receives and processes webhooks for Stripe Connect.
+     *
+     * Stripe Connect用のWebhookを受信して処理します。
+     */
+    readonly stripeWebhookConnect: (options?: StripePurchaseWorkersOptions) => WorkersData;
+    /**
+     * Webhook for proper redirection when 3D Secure authentication is required.
+     *
+     * 3Dセキュア認証が必要な場合、適切なリダイレクトを行うためのWebhookです。
+     */
+    readonly stripeWebhookSecure: (options?: StripePurchaseWorkersOptions) => WorkersData;
+};

package/dist/functions.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Functions = void 0;
+const masamune_cloudflare_1 = require("@mathrunet/masamune_cloudflare");
+/**
+ * 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`で別途提供します。
+ */
+exports.Functions = {
+    /**
+     * Performs various Stripe processes (mode-based actions).
+     *
+     * Stripeの各種処理（mode分岐のアクション）を実行します。
+     */
+    stripe: (options = {}) => new masamune_cloudflare_1.WorkersData({ path: "/stripe", func: require("./workers/stripe"), options: options }),
+    /**
+     * Receives and processes webhooks from Stripe.
+     *
+     * StripeからのWebhookを受け取り処理を行います。
+     */
+    stripeWebhook: (options = {}) => new masamune_cloudflare_1.WorkersData({ path: "/stripe/webhook", func: require("./workers/stripe_webhook"), options: options }),
+    /**
+     * Receives and processes webhooks for Stripe Connect.
+     *
+     * Stripe Connect用のWebhookを受信して処理します。
+     */
+    stripeWebhookConnect: (options = {}) => new masamune_cloudflare_1.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 = {}) => new masamune_cloudflare_1.WorkersData({ path: "/stripe/webhook/secure", func: require("./workers/stripe_webhook_secure"), options: options }),
+};
+//# sourceMappingURL=functions.js.map

package/dist/functions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.js","sourceRoot":"","sources":["../src/functions.ts"],"names":[],"mappings":";;;AAAA,wEAA6D;AAG7D;;;;;;;;;;;;;;;GAeG;AACU,QAAA,SAAS,GAAG;IACrB;;;;OAIG;IACH,MAAM,EAAE,CAAC,UAAwC,EAAE,EAAE,EAAE,CAAC,IAAI,iCAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,kBAAkB,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAEjJ;;;;OAIG;IACH,aAAa,EAAE,CAAC,UAAwC,EAAE,EAAE,EAAE,CAAC,IAAI,iCAAW,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,OAAO,CAAC,0BAA0B,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAExK;;;;OAIG;IACH,oBAAoB,EAAE,CAAC,UAAwC,EAAE,EAAE,EAAE,CAAC,IAAI,iCAAW,CAAC,EAAE,IAAI,EAAE,yBAAyB,EAAE,IAAI,EAAE,OAAO,CAAC,kCAAkC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAE/L;;;;OAIG;IACH,mBAAmB,EAAE,CAAC,UAAwC,EAAE,EAAE,EAAE,CAAC,IAAI,iCAAW,CAAC,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,OAAO,CAAC,iCAAiC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;CACtL,CAAC"}

package/dist/index.d.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/dist/index.js

@@ -0,0 +1,42 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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
+ */
+__exportStar(require("@mathrunet/masamune"), exports);
+__exportStar(require("@mathrunet/masamune_cloudflare"), exports);
+__exportStar(require("./functions"), exports);
+__exportStar(require("./lib/options"), exports);
+__exportStar(require("./lib/stripe_client"), exports);
+__exportStar(require("./lib/purchase/interface"), exports);
+__exportStar(require("./lib/purchase/d1_purchase_store"), exports);
+__exportStar(require("./lib/purchase/helpers"), exports);
+__exportStar(require("./lib/purchase/sync_payment"), exports);
+__exportStar(require("./lib/meter/interface"), exports);
+__exportStar(require("./lib/meter/stripe_meter_client"), exports);
+__exportStar(require("./lib/meter/flush_meter"), exports);
+__exportStar(require("./lib/meter/record_usage"), exports);
+__exportStar(require("./lib/meter/d1_usage_event_store"), exports);
+__exportStar(require("./lib/meter/kv_usage_buffer"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;GASG;AACH,sDAAoC;AACpC,iEAA+C;AAC/C,8CAA4B;AAC5B,gDAA8B;AAC9B,sDAAoC;AACpC,2DAAyC;AACzC,mEAAiD;AACjD,yDAAuC;AACvC,8DAA4C;AAC5C,wDAAsC;AACtC,kEAAgD;AAChD,0DAAwC;AACxC,2DAAyC;AACzC,mEAAiD;AACjD,8DAA4C"}

package/dist/lib/meter/d1_usage_event_store.d.ts

@@ -0,0 +1,128 @@
+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 declare class D1UsageEventStore implements StripeUsageEventStore {
+    /**
+     * [StripeUsageEventStore] backed by Cloudflare D1 (or any compatible SQL database).
+     *
+     * Cloudflare D1（または互換SQLデータベース）を用いた[StripeUsageEventStore]。
+     */
+    constructor(db: SqlDatabaseLike, options?: D1UsageEventStoreOptions);
+    private readonly _db;
+    private readonly _table;
+    private readonly _id;
+    private readonly _customerKey;
+    private readonly _endpoint;
+    private readonly _units;
+    private readonly _source;
+    private readonly _createdAt;
+    private readonly _flushed;
+    /**
+     * Persist a usage event with `flushed = 0`.
+     *
+     * 使用量イベントを未送信状態で永続化します。
+     */
+    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>;
+}

package/dist/lib/meter/d1_usage_event_store.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.D1UsageEventStore = void 0;
+/**
+ * [StripeUsageEventStore] backed by Cloudflare D1 (or any compatible SQL database).
+ *
+ * Cloudflare D1（または互換SQLデータベース）を用いた[StripeUsageEventStore]。
+ */
+class D1UsageEventStore {
+    /**
+     * [StripeUsageEventStore] backed by Cloudflare D1 (or any compatible SQL database).
+     *
+     * Cloudflare D1（または互換SQLデータベース）を用いた[StripeUsageEventStore]。
+     */
+    constructor(db, options = {}) {
+        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";
+    }
+    _db;
+    _table;
+    _id;
+    _customerKey;
+    _endpoint;
+    _units;
+    _source;
+    _createdAt;
+    _flushed;
+    /**
+     * Persist a usage event with `flushed = 0`.
+     *
+     * 使用量イベントを未送信状態で永続化します。
+     */
+    async insert(event) {
+        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) {
+        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();
+        return pending.results ?? [];
+    }
+    /**
+     * Mark the given events as flushed to Stripe.
+     *
+     * 指定したイベントをStripe送信済みとして記録します。
+     */
+    async markFlushed(ids) {
+        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();
+    }
+}
+exports.D1UsageEventStore = D1UsageEventStore;
+//# sourceMappingURL=d1_usage_event_store.js.map

package/dist/lib/meter/d1_usage_event_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1_usage_event_store.js","sourceRoot":"","sources":["../../../src/lib/meter/d1_usage_event_store.ts"],"names":[],"mappings":";;;AA6FA;;;;GAIG;AACH,MAAa,iBAAiB;IAC1B;;;;OAIG;IACH,YAAY,EAAmB,EAAE,UAAoC,EAAE;QACnE,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC;QAC9C,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC;QACpC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,iBAAiB,IAAI,YAAY,CAAC;QAC9D,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,cAAc,IAAI,UAAU,CAAC;QACtD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC;QAC7C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,YAAY,IAAI,iBAAiB,CAAC;QACzD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,eAAe,IAAI,YAAY,CAAC;QAC1D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,aAAa,IAAI,mBAAmB,CAAC;IACjE,CAAC;IAEgB,GAAG,CAAkB;IACrB,MAAM,CAAS;IACf,GAAG,CAAS;IACZ,YAAY,CAAS;IACrB,SAAS,CAAS;IAClB,MAAM,CAAS;IACf,OAAO,CAAS;IAChB,UAAU,CAAS;IACnB,QAAQ,CAAS;IAElC;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,KAAuB;QAChC,MAAM,IAAI,CAAC,GAAG;aACT,OAAO,CACJ,eAAe,IAAI,CAAC,MAAM;qBACrB,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,QAAQ;8CAC/F,CACjC;aACA,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC;aAC7F,GAAG,EAAE,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,WAAmB;QACjC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG;aACzB,OAAO,CACJ,UAAU,IAAI,CAAC,GAAG,WAAW,IAAI,CAAC,MAAM,kBAAkB,IAAI,CAAC,MAAM;yBAC5D,IAAI,CAAC,YAAY,YAAY,IAAI,CAAC,QAAQ,MAAM,CAC5D;aACA,IAAI,CAAC,WAAW,CAAC;aACjB,GAAG,EAAiC,CAAC;QAC1C,OAAO,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,GAAa;QAC3B,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YAClB,OAAO;QACX,CAAC;QACD,MAAM,YAAY,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClD,MAAM,IAAI,CAAC,GAAG;aACT,OAAO,CACJ,UAAU,IAAI,CAAC,MAAM,QAAQ,IAAI,CAAC,QAAQ,cAAc,IAAI,CAAC,GAAG,QAAQ,YAAY,GAAG,CAC1F;aACA,IAAI,CAAC,GAAG,GAAG,CAAC;aACZ,GAAG,EAAE,CAAC;IACf,CAAC;CACJ;AA7ED,8CA6EC"}

package/dist/lib/meter/flush_meter.d.ts

@@ -0,0 +1,19 @@
+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 declare function flushStripeMeter(options: {
+    store: StripeUsageEventStore;
+    client: StripeMeterClient;
+    customerKey: string;
+    stripeCustomerId: string | null | undefined;
+}): Promise<boolean>;

package/dist/lib/meter/flush_meter.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flushStripeMeter = flushStripeMeter;
+/**
+ * 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`を返します（イベントは未送信のまま残り、次回再送されます）。
+ */
+async function flushStripeMeter(options) {
+    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;
+}
+//# sourceMappingURL=flush_meter.js.map

package/dist/lib/meter/flush_meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush_meter.js","sourceRoot":"","sources":["../../../src/lib/meter/flush_meter.ts"],"names":[],"mappings":";;AAcA,4CA8BC;AAzCD;;;;;;;;;;GAUG;AACI,KAAK,UAAU,gBAAgB,CAAC,OAKtC;IACG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC;QACvD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC5D,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,8CAA8C;IAC9C,kDAAkD;IAClD,MAAM,UAAU,GAAG,GAAG,OAAO,CAAC,WAAW,IAAI,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;IACnE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC;QAC7C,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,KAAK,EAAE,KAAK;QACZ,UAAU,EAAE,UAAU;KACzB,CAAC,CAAC;IACH,IAAI,CAAC,IAAI,EAAE,CAAC;QACR,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,MAAM,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC;AAChB,CAAC"}