Expand Stripe billing surface simulation

[midagedev]

Summary

• Add Stripe-shaped invoice preview/upcoming proration for subscription item price changes.
• Add customer-level default invoice renewal outcomes, failed-renewal webhook evidence, and pending refund settlement on test-clock advance.
• Extend PaymentIntent SCA responses, refund/credit-note/dispute APIs and fixtures, connected-account fixture seeding, fixture dry-run validation, and timeline filtering.

Validation

• go test ./...
• git diff --check
• forbidden keyword scan: rg -n "Dentbird|dentbird|imagoworks|DS4|ds4|DS1|ds1" . --glob "!vendor/" --glob "!node_modules/" --glob "!.git/**"

Stripe references used

• https://docs.stripe.com/api/invoices/create_preview
• https://docs.stripe.com/api/payment_intents/object
• https://docs.stripe.com/api/disputes/object

[claude]

APPROVE

요약

이 PR은 Stripe 결제 시뮬레이션 표면을 확장하여 invoice preview proration, customer default invoice outcome, pending refund settlement, PaymentIntent redirect_to_url, refund/credit-note/dispute 상태 변경, fixture validate, connected account fixture, dispute fixture, timeline 필터링 기능을 추가합니다.

주요 변경 사항

1. Invoice Preview/Upcoming Proration

• POST /v1/invoices/create_preview와 GET/POST /v1/invoices/upcoming 엔드포인트 구현
• subscription-update 시나리오에 대한 Stripe-shaped proration 계산
• subscription_details[items][0][price], subscription_details[proration_behavior], subscription_details[proration_date] 파라미터 지원
• internal/api/api.go

2. Customer Default Invoice Outcome

• customer fixture의 default_invoice_outcome 또는 billtap_default_invoice_outcome 메타데이터로 갱신 실패 시나리오 지원
• subscription 갱신 시 customer-level default outcome fallback 로직 추가
• internal/billing/service.go

3. Pending Refund Settlement

• refund fixture에 status: pending, settle_at, test_clock 지원
• test clock advance로 pending refund를 succeeded로 전환하고 charge.refund.updated webhook emit
• internal/billing/service.go

4. PaymentIntent redirect_to_url Next Action

• billtap_next_action_type: redirect_to_url와 return_url 메타데이터로 local redirect URL next_action 지원
• 기존 use_stripe_sdk 옵션과 함께 두 가지 SCA simulation 방식 제공
• internal/api/api.go

5. Refund Update/Cancel APIs

• POST /v1/refunds/{id}로 refund status 업데이트 지원
• POST /v1/refunds/{id}/cancel로 refund 취소 지원
• status 변경 시 charge.refund.updated webhook emit
• internal/api/api.go

6. Credit Note Void

• POST /v1/credit_notes/{id}/void 엔드포인트 구현
• credit_note.voided webhook emit
• fixture에서 status: void 지원
• internal/api/api.go

7. Dispute Evidence Update

• POST /v1/disputes/{id}로 evidence와 status 업데이트 지원
• charge.dispute.updated, charge.dispute.funds_withdrawn webhook emit
• fixture에서 dispute seed 지원
• internal/api/local_evidence.go

8. Fixture Validate API

• POST /api/fixtures/validate로 dry-run fixture validation 지원
• connected_accounts, disputes 포함한 fixture pack 스키마 및 semantic 검증
• internal/api/api.go

9. Timeline Filter Extension

• object_type과 object_id로 generic timeline 필터링 지원
• 기존 customer/checkout/subscription/invoice/payment_intent 특정 필터와 병행
• internal/api/api.go

검증 관찰

• 테스트 커버리지: TestInvoicePreviewProrationAndUpcoming, TestCustomerDefaultInvoiceOutcomeFailsRenewal, TestRefundTimingCreditVoidFixtureValidateAndDisputes 테스트 추가
• Compatibility claims registry: 140개 → 145개 claim 업데이트
• 문서 업데이트: COMPATIBILITY.md, API_VALIDATION_AND_ERROR_SIMULATION.md, specs/000-product/contracts/api.md에 새 기능 명시
• PR description에 명시된 validation 명령어 포함

Security & Safety 확인

• 실제 결제 처리 경로 없음: 모든 simulation은 local state machine
• Real card data 저장하지 않음: sandbox metadata로만 outcome 제어
• Production boundary 유지: docs에 local simulation 범위 명확히 명시
• Webhook semantics 유지: 모든 webhook event는 proper signature와 retry 지원

Billing State Correctness 확인

• Subscription renewal 시 customer default outcome fallback은 subscription metadata outcome을 override하지 않고 순서대로 확인
• Refund pending→succeeded 전환은 test clock attachment 및 settle_at timestamp 기반으로 deterministic
• Invoice preview proration은 current_period_start/end bounds 기반으로 계산하며 behavior=none인 경우 line 없음

Suggestion (비차단)

1. internal/api/api.go#L214-L215: compatibility claim 경로 일치 로직이 { placeholder 포함 여부로 분기하는데, 이는 path parameter가 없는 경로에 대한 optimization으로 보입니다. 의도대로 동작하지만 향후 path parameter가 있는 경로 추가 시 주의 필요.

2. internal/billing/service.go#L1443-1461: normalizeInvoiceOutcome과 IsSupportedInvoiceOutcome 함수가 payment intent outcome validation을 재사용하는데, 이는 설계적으로 합리적입니다. 다만 invoice outcome과 payment intent outcome의 차이가 발생할 경우를 대비한 분리 고려.

결론

Billing state correctness, webhook reliability, safety 측면에서 regression 없이 Stripe billing simulation 표면을 확장한 PR입니다. Fixture/assert ergonomics 개선과 compatibility claims 업데이트도 포함되어 있어 G13 Stripe API Compatibility Expansion Roadmap 진행에 부합합니다.

_{Reviewed by Z.ai GLM via Claude Code Action}