Claude × Stripe Meter Events で従量課金 SaaS を構築する実装ガイド

// src/lib/claude-with-metering.ts
import Anthropic from "@anthropic-ai/sdk";
import { sendMeterEvent } from "./stripe-meter";
 
const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY!,
});
 
export interface ClaudeRequest {
  userId: string;
  stripeCustomerId: string;
  prompt: string;
  model?: string;
}
 
export async function callClaudeWithMetering(req: ClaudeRequest) {
  // 1. 上限チェック（KV から消費量を読み取る）
  const usageThisMonth = await getMonthlyUsage(req.userId);
  if (usageThisMonth > 5_000_000) {
    // 5M トークン上限を超えたら強制停止（ランナウェイ防止）
    throw new Error("Monthly token limit exceeded");
  }
 
  // 2. Claude API 呼び出し
  const response = await anthropic.messages.create({
    model: req.model ?? "claude-sonnet-4-6",
    max_tokens: 2048,
    messages: [{ role: "user", content: req.prompt }],
  });
 
  // 3. usage フィールドからトークン数を取り出す
  const inputTokens = response.usage.input_tokens;
  const outputTokens = response.usage.output_tokens;
  const totalTokens = inputTokens + outputTokens;
 
  // 4. Stripe Meter Events に送信（冪等性キー付き）
  // response.id は Anthropic が発行するユニークIDなので、これを冪等性キーに使う
  await sendMeterEvent({
    customerId: req.stripeCustomerId,
    tokens: totalTokens,
    identifier: response.id, // 重複排除キー
  });
 
  // 5. KV にローカル消費量を加算（上限チェック用）
  await incrementMonthlyUsage(req.userId, totalTokens);
 
  return {
    content: response.content,
    usage: { inputTokens, outputTokens, totalTokens },
  };
}

// src/lib/stripe-meter.ts
import Stripe from "stripe";
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-10-28.acacia",
});
 
export interface MeterEventArgs {
  customerId: string;
  tokens: number;
  identifier: string; // 冪等性キー
}
 
export async function sendMeterEvent(args: MeterEventArgs) {
  let attempt = 0;
  const maxAttempts = 3;
  let lastError: unknown;
 
  while (attempt < maxAttempts) {
    try {
      const event = await stripe.billing.meterEvents.create({
        event_name: "claude_token_usage",
        payload: {
          stripe_customer_id: args.customerId,
          tokens: args.tokens.toString(), // 文字列で送る
        },
        identifier: args.identifier, // 同じ identifier は1回しか集計されない
      });
      return event;
    } catch (err) {
      lastError = err;
      attempt++;
      // 指数バックオフ: 1秒 → 2秒 → 4秒
      await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt - 1)));
    }
  }
 
  // 3回失敗したら、別途 Dead Letter Queue に保存して後でリトライ
  // ここでエラーを throw してしまうと、Claude API は成功したのに課金できない状況になる
  console.error("[CRITICAL] Meter event failed after 3 attempts", lastError);
  await saveToDLQ(args);
  return null;
}

// src/lib/rate-limiter.ts
import type { KVNamespace } from "@cloudflare/workers-types";
 
interface RateLimiterArgs {
  kv: KVNamespace;
  userId: string;
  tokens: number;
}
 
export async function checkAndIncrementUsage(args: RateLimiterArgs) {
  const now = new Date();
  const monthKey = `usage:${args.userId}:${now.toISOString().slice(0, 7)}`; // usage:user_xxx:2026-05
  const minuteKey = `rate:${args.userId}:${now.toISOString().slice(0, 16)}`;
 
  // 第1層: 月間上限（5M tokens）
  const monthly = parseInt((await args.kv.get(monthKey)) ?? "0", 10);
  if (monthly + args.tokens > 5_000_000) {
    throw new Error("Monthly limit exceeded");
  }
 
  // 第2層: 1分間上限（50K tokens）
  const perMinute = parseInt((await args.kv.get(minuteKey)) ?? "0", 10);
  if (perMinute + args.tokens > 50_000) {
    throw new Error("Rate limit: too many tokens per minute");
  }
 
  // 上限に当たらなければ加算
  // expirationTtl で自動削除されるため、月初リセットバッチ不要
  await args.kv.put(monthKey, String(monthly + args.tokens), {
    expirationTtl: 35 * 24 * 60 * 60, // 35日後に自動削除
  });
  await args.kv.put(minuteKey, String(perMinute + args.tokens), {
    expirationTtl: 120, // 2分後に自動削除
  });
}

// src/api/stripe-webhook.ts (Cloudflare Workers / Hono 想定)
import type { Hono } from "hono";
import Stripe from "stripe";
 
export const handleStripeWebhook = async (c: any) => {
  const stripe = new Stripe(c.env.STRIPE_SECRET_KEY, {
    apiVersion: "2024-10-28.acacia",
  });
  const sig = c.req.header("stripe-signature");
  const body = await c.req.text();
 
  let event: Stripe.Event;
  try {
    // Cloudflare Workers では constructEventAsync を使う（同期版は動かない）
    event = await stripe.webhooks.constructEventAsync(
      body,
      sig!,
      c.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return c.json({ error: "Invalid signature" }, 400);
  }
 
  // 月次請求書イベントを購読して、当月使用量を KV に書き戻す
  if (event.type === "invoice.created") {
    const invoice = event.data.object as Stripe.Invoice;
    const customerId = invoice.customer as string;
    // line_items から meter 関連のライン情報を取得して KV に書き戻す処理
    // ...
  }
 
  return c.json({ received: true });
};

// src/api/portal-session.ts
import Stripe from "stripe";
 
export const createPortalSession = async (
  stripeCustomerId: string,
  returnUrl: string
) => {
  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
    apiVersion: "2024-10-28.acacia",
  });
  const session = await stripe.billingPortal.sessions.create({
    customer: stripeCustomerId,
    return_url: returnUrl,
  });
  // session.url にユーザーをリダイレクトする
  return session.url;
};

// src/api/refund-meter-charges.ts
import Stripe from "stripe";
 
export const issueMeterRefund = async (
  invoiceId: string,
  refundAmountInCents: number,
  reason: string
) => {
  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
    apiVersion: "2024-10-28.acacia",
  });
 
  // クレジットノートで返金（次回請求時に相殺される）
  const creditNote = await stripe.creditNotes.create({
    invoice: invoiceId,
    amount: refundAmountInCents,
    credit_amount: refundAmountInCents,
    reason: "duplicate", // duplicate / fraudulent / order_change / product_unsatisfactory
    memo: reason,
  });
 
  return creditNote;
};

// 概念的な実装スケッチ
class MeterEventBatcher {
  private buffer: MeterEventArgs[] = [];
  private timer: ReturnType<typeof setTimeout> | null = null;
 
  add(event: MeterEventArgs) {
    this.buffer.push(event);
    if (!this.timer) {
      this.timer = setTimeout(() => this.flush(), 1000);
    }
    if (this.buffer.length >= 100) {
      this.flush();
    }
  }
 
  private async flush() {
    if (this.timer) {
      clearTimeout(this.timer);
      this.timer = null;
    }
    const batch = this.buffer.splice(0);
    // 並列送信（順序は問わないが冪等性キーで重複は防げる）
    await Promise.all(batch.map(sendMeterEvent));
  }
}