Antigravity AI エージェントで作る Stripe Dunning パイプライン — 課金失敗をチャーンに変えない実装ガイド

// app/api/webhook/stripe-billing/route.ts
import Stripe from "stripe";
import { getCloudflareContext } from "@opennextjs/cloudflare";
 
// 事前に Cloudflare Worker のシークレットとして設定:
//   STRIPE_SECRET_KEY=sk_live_...（本番）/ sk_test_...（テスト）
//   STRIPE_WEBHOOK_BILLING_SECRET=whsec_...
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2025-08-27.basil",
});
 
export async function POST(req: Request) {
  const sig = req.headers.get("stripe-signature");
  if (!sig) return new Response("missing signature", { status: 400 });
 
  const body = await req.text();
  let event: Stripe.Event;
  try {
    event = await stripe.webhooks.constructEventAsync(
      body,
      sig,
      process.env.STRIPE_WEBHOOK_BILLING_SECRET!,
      undefined,
      Stripe.createSubtleCryptoProvider() // Cloudflare Workers では必須
    );
  } catch (err) {
    console.error("webhook signature verification failed", err);
    return new Response("invalid signature", { status: 400 });
  }
 
  // 冪等性: event.id を一意キーに使う
  const { env } = getCloudflareContext();
  const seen = await env.BILLING_KV.get(`evt:${event.id}`);
  if (seen) {
    return new Response("duplicate", { status: 200 });
  }
  await env.BILLING_KV.put(`evt:${event.id}`, "1", { expirationTtl: 60 * 60 * 24 * 7 });
 
  // 課金失敗だけを Dunning パイプラインに流す
  if (event.type === "invoice.payment_failed") {
    await enqueueDunning(event.data.object as Stripe.Invoice, env);
  }
 
  return new Response("ok", { status: 200 });
}

// lib/dunning/normalize.ts
export type DunningContext = {
  customerId: string;
  customerEmail: string;
  amountDue: number; // 最小単位 (JPY ならそのまま、USD なら cents)
  currency: string;
  failureReason: "card_expired" | "insufficient_funds" | "authentication_required" | "do_not_honor" | "unknown";
  attemptCount: number; // Stripe の next_payment_attempt 回目
  planTier: "basic" | "pro" | "team";
  isAnnual: boolean;
  customerSegment: "trial" | "new" | "loyal" | "winback";
  lastSuccessfulPaymentAt: number | null; // unix秒
  totalLifetimeValueJpy: number;
};
 
export async function buildDunningContext(invoice: Stripe.Invoice, env: Env): Promise<DunningContext> {
  const customer = await stripe.customers.retrieve(invoice.customer as string);
  const subs = await stripe.subscriptions.list({ customer: invoice.customer as string, limit: 1 });
  const sub = subs.data[0];
 
  // Stripe の decline_code → 自社ドメイン語彙へ
  const code = invoice.last_finalization_error?.decline_code ?? invoice.last_payment_error?.decline_code;
  const failureReason = mapDeclineCode(code);
 
  // 失敗理由が分からないとエージェントが過剰反応するので必ず "unknown" にフォールバック
  if (!failureReason) {
    console.warn("unmapped decline_code", code, "invoice", invoice.id);
  }
 
  return {
    customerId: invoice.customer as string,
    customerEmail: (customer as Stripe.Customer).email ?? "",
    amountDue: invoice.amount_due,
    currency: invoice.currency,
    failureReason: failureReason ?? "unknown",
    attemptCount: invoice.attempt_count,
    planTier: detectPlanTier(sub),
    isAnnual: sub.items.data[0].price.recurring?.interval === "year",
    customerSegment: await detectSegment(invoice.customer as string, env),
    lastSuccessfulPaymentAt: await getLastSuccessfulPaymentAt(invoice.customer as string, env),
    totalLifetimeValueJpy: await getLtvJpy(invoice.customer as string, env),
  };
}
 
function mapDeclineCode(code?: string | null): DunningContext["failureReason"] | undefined {
  switch (code) {
    case "expired_card": return "card_expired";
    case "insufficient_funds": return "insufficient_funds";
    case "authentication_required": return "authentication_required";
    case "do_not_honor": return "do_not_honor";
    default: return undefined;
  }
}

# Dunning Orchestrator Agent
 
## Role
Stripe の課金失敗イベントを受け取り、顧客とビジネスの双方にとって最も健全なリカバリアクションを 1 つだけ選んで実行する。
 
## Available tools
- send_email(template_id, customer_email, variables): Resend 経由でメール送信
- post_slack(channel, blocks): Slack に通知
- update_customer_state(customer_id, state, note): 内部 KV を更新
- request_stripe_smart_retry(invoice_id, schedule): Stripe Smart Retries の再スケジュール
- offer_winback_discount(customer_id, percent_off, valid_days): クーポン発行 + メール送信
- escalate_to_human(reason): 自動対応を諦め、サポートにエスカレーション
 
## Decision policy
1. failureReason = "card_expired" → 顧客にカード更新リンクを送る (template "card_update_request")
2. failureReason = "insufficient_funds" かつ attemptCount <= 2 → Stripe Smart Retries に任せる + 顧客には控えめな通知 (template "soft_payment_reminder")
3. attemptCount >= 3 かつ planTier in ["pro","team"] かつ totalLifetimeValueJpy > 30000 → escalate_to_human
4. customerSegment = "loyal" かつ failureReason != "card_expired" → offer_winback_discount(percent_off=20, valid_days=14)
5. 不明なケースは escalate_to_human + Slack 通知
 
## Hard constraints
- 同じ顧客に 24 時間以内に 2 通以上のメールを送らない
- send_email を呼ぶ前に customer_email が空でないことを必ず確認する
- offer_winback_discount は同一顧客に対して 90 日に 1 回まで

// lib/dunning/run-agent.ts
import { GoogleGenAI, FunctionDeclaration } from "@google/genai";
 
const tools: FunctionDeclaration[] = [
  {
    name: "send_email",
    description: "送信テンプレートと変数を指定してメール送信",
    parameters: {
      type: "object",
      properties: {
        template_id: { type: "string", enum: ["card_update_request", "soft_payment_reminder", "winback_offer", "final_warning"] },
        customer_email: { type: "string" },
        variables: { type: "object" },
      },
      required: ["template_id", "customer_email"],
    },
  },
  // ... 他のツール宣言を同様に
];
 
export async function runDunningAgent(ctx: DunningContext, env: Env) {
  // 必須: ハード制約のチェック (エージェントの判断より優先)
  if (!ctx.customerEmail) {
    await postSlack(env, `[dunning] customer ${ctx.customerId} has no email — skipping`);
    return { action: "skipped", reason: "no_email" };
  }
 
  const recent = await env.BILLING_KV.get(`mail-throttle:${ctx.customerId}`);
  if (recent) {
    return { action: "skipped", reason: "throttled" };
  }
 
  const ai = new GoogleGenAI({ apiKey: env.GEMINI_API_KEY });
  const response = await ai.models.generateContent({
    model: "gemini-3-pro",
    contents: [
      { role: "user", parts: [{ text: buildPrompt(ctx) }] },
    ],
    config: {
      tools: [{ functionDeclarations: tools }],
      systemInstruction: await loadAgentMd(env, "dunning-orchestrator.md"),
      temperature: 0.2, // 判断の再現性を上げる
    },
  });
 
  // function_call を 1 つだけ実行する設計にしている
  const call = response.functionCalls?.[0];
  if (!call) {
    await postSlack(env, `[dunning] agent returned no action for ${ctx.customerId}`);
    return { action: "no_action" };
  }
 
  const result = await dispatchTool(call.name, call.args, ctx, env);
  await env.BILLING_KV.put(
    `mail-throttle:${ctx.customerId}`,
    "1",
    { expirationTtl: 60 * 60 * 24 } // 24h スロットル
  );
 
  return { action: call.name, ...result };
}

// emails/CardUpdateRequest.tsx
import { Body, Container, Heading, Text, Button, Html } from "@react-email/components";
 
export default function CardUpdateRequest({
  firstName,
  amountFormatted,
  updateLink,
  empathyParagraph, // Gemini が文脈に応じて生成
}: { firstName: string; amountFormatted: string; updateLink: string; empathyParagraph: string }) {
  return (
    <Html>
      <Body>
        <Container>
          <Heading as="h2">{firstName} さん、お支払い情報のご確認をお願いできますか</Heading>
          <Text>{empathyParagraph}</Text>
          <Text>今回お試しした金額は {amountFormatted} です。下のボタンから新しいカードに更新いただけます。</Text>
          <Button href={updateLink}>カード情報を更新する</Button>
          <Text>もしすでに対応済みでしたら、本メールは無視していただいて構いません。</Text>
        </Container>
      </Body>
    </Html>
  );
}

// lib/dunning/slack.ts
export function buildEscalationBlocks(ctx: DunningContext, reason: string) {
  return [
    {
      type: "header",
      text: { type: "plain_text", text: `:rotating_light: Dunning escalation` },
    },
    {
      type: "section",
      fields: [
        { type: "mrkdwn", text: `*顧客*\n<https://dashboard.stripe.com/customers/${ctx.customerId}|${ctx.customerEmail}>` },
        { type: "mrkdwn", text: `*プラン*\n${ctx.planTier} (${ctx.isAnnual ? "年額" : "月額"})` },
        { type: "mrkdwn", text: `*金額*\n${ctx.amountDue / 100} ${ctx.currency.toUpperCase()}` },
        { type: "mrkdwn", text: `*失敗理由*\n${ctx.failureReason}` },
        { type: "mrkdwn", text: `*試行回数*\n${ctx.attemptCount}` },
        { type: "mrkdwn", text: `*LTV (JPY)*\n¥${ctx.totalLifetimeValueJpy.toLocaleString()}` },
      ],
    },
    {
      type: "section",
      text: { type: "mrkdwn", text: `*Why escalated*\n${reason}` },
    },
    {
      type: "actions",
      elements: [
        { type: "button", text: { type: "plain_text", text: "Send winback offer" }, action_id: "dunning_winback" },
        { type: "button", text: { type: "plain_text", text: "Mark as lost" }, action_id: "dunning_mark_lost", style: "danger" },
      ],
    },
  ];
}