feat(billing): fetch authoritative Stripe invoice state

[seonghobae]

Buyer/data-integrity objective

Refs #488. This Draft child of the Stripe entitlement-policy stack adds the authoritative Invoice read boundary required before paid Invoice evidence can become an entitlement-policy input. It verifies exact server-owned Invoice, Customer, Subscription, and organization authority; bounds Stripe transport and response parsing; supports the current Basil Invoice provenance shape and the legacy pre-Basil shape without trusting metadata as sole identity authority; and returns immutable payment evidence only.

Exact current stack

• protected develop: df0fa17bd5035af6455c889022c540b4f439e3d6;
• exact parent/base feat(billing): derive monotonic Stripe entitlement policy #528: feat/stripe-entitlement-policy-488@9da3f3663a80cf20aa9562132eb3d1b7f5fcb1d0;
• exact contributor head: e26164934ddbe7417635b6839e78adf29f6d6197;
• exact parent→child comparison: ahead 2, behind 0, exact parent as merge base, seven changed paths, CHANGELOG.md +5/-0 and coverage contract +25/-0.

The effective delta is limited to the additive Unreleased changelog, Invoice doctoring, package/coverage registration, server/stripe_invoice_provider.mjs, and two focused Invoice-reader regressions. No auth/session, Clearfolio, attachment, existing billing persistence, application route, dependency lockfile, workflow, scanner suppression, or branch-protection artifact is changed.

TDD and focused evidence

Test-only commit a83b002210c2448f7cdfaaab94b506ab1c581473 registered a realistic Invoice provider contract before the production module existed, making the new boundary RED at module resolution. Implementation commit e26164934ddbe7417635b6839e78adf29f6d6197 added the reader, edge coverage, additive parent-style coverage contract, doctoring, and changelog evidence.

Private focused execution after implementation passed all seven Invoice-reader subtests and produced 100% line / 100% branch / 100% function coverage for server/stripe_invoice_provider.mjs. Hosted exact-head evidence remains authoritative for integration.

Provider and compatibility contract

• one exact GET https://api.stripe.com/v1/invoices/{invoice} with a 15-second abort budget and redirects rejected;
• 256 KiB declared and streamed response ceilings before fatal UTF-8/JSON parsing;
• stable sanitized provider errors and distinct 404/unavailable classifications;
• exact Invoice, Customer, and Subscription identity checks before evidence is returned;
• current Stripe Basil parent.type=subscription_details / parent.subscription_details.subscription support plus legacy top-level subscription support, failing closed when both shapes disagree;
• optional Subscription metadata can detect a tenant contradiction but cannot replace server-owned identity authority;
• canonical Stripe Invoice statuses plus paid flag, status_transitions.paid_at, currency, amount, and timestamp consistency checks; and
• no implicit Stripe-Version pin in this slice, preserving the existing account-default API-version boundary while rejecting provider shapes outside the tested current/legacy contracts.

Stripe's current Invoice reference exposes parent.subscription_details.subscription; Stripe's 2025-03-31.basil breaking-change record explicitly moved Subscription provenance into that parent shape while deprecating the prior top-level fields. The doctoring record captures the current/legacy compatibility boundary and APA 7 references to Stripe's primary documentation.

Current exact-head evidence

Fresh repository-native workflows for unchanged head e26164934ddbe7417635b6839e78adf29f6d6197 are queued and therefore non-passing:

• Server Tests 32277320425;
• Dependency Review 32277320435; and
• OSV Scanner 32277320865.

There are no submitted reviews or review threads on this exact head and no qualifying independent current-head approval. Queued, pending, skipped-required, cancelled, absent, neutral-required, failed, stale, predecessor, synthetic, status-only, author-only, or model-only evidence is non-passing.

Scope boundary

This PR does not persist Invoice observations, mutate orgs.plan, persist entitlement claims, or grant access. Normalized Invoice/payment persistence, transactional claim/audit storage, reversible entitlement application, operator recovery, and end-to-end out-of-order convergence remain subsequent #488 work.

Remain Draft. Do not integrate independently of #528 and its prerequisite stack. After the stack reaches protected develop, reconcile this bounded semantic delta onto the resulting live head and regenerate every then-applicable exact-head deterministic/browser/statement/branch/function/line coverage/docstring/SAST/security/dependency/supply-chain/package/provenance/migration/recovery/review gate required by live policy.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 58ae3c8d-e50d-424d-8a9e-20969eaf9443

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}