reasonkit-web 0.1.7

// Allow missing docs in this module - stripe integration is internal
#![allow(missing_docs)]

//! Stripe Webhook Handler Module
//!
//! This module provides secure, production-ready Stripe webhook handling for SaaS
//! subscription services. It implements:
//!
//! - **Signature Verification**: HMAC-SHA256 validation of the `stripe-signature` header
//! - **Idempotency**: Deduplication of webhook deliveries using event IDs
//! - **Async Processing**: Non-blocking webhook handling with background task execution
//! - **Event Handling**: Support for subscription, invoice, and customer events
//! - **Error Recovery**: Configurable retry logic with exponential backoff
//!
//! # Architecture
//!
//! ```text
//! Request -> Signature Verify -> Idempotency Check -> Ack (200) -> Async Process
//!                   |                    |                              |
//!                   v                    v                              v
//!              400/401              202 (already)              Background Task
//! ```
//!
//! # Security
//!
//! - CONS-003 COMPLIANT: Webhook signing secret loaded from environment
//! - Constant-time signature comparison to prevent timing attacks
//! - Raw body parsing to ensure signature verification works correctly
//!
//! # Example
//!
//! ```rust,no_run
//! use reasonkit_web::stripe::{
//!     stripe_webhook_router, CustomerEvent, InvoiceEvent, StripeWebhookConfig,
//!     StripeWebhookState, SubscriptionEvent, SubscriptionHandler,
//! };
//! use std::sync::Arc;
//!
//! #[tokio::main]
//! async fn main() -> anyhow::Result<()> {
//!     let config = StripeWebhookConfig::from_env()?;
//!     let handler = Arc::new(MySubscriptionHandler);
//!     let (state, processor_handle) = StripeWebhookState::new(config, handler);
//!
//!     // Run background processing loop
//!     tokio::spawn(async move {
//!         processor_handle.run().await;
//!     });
//!
//!     let _app = stripe_webhook_router(Arc::new(state));
//!     // ... serve with axum
//!     Ok(())
//! }
//!
//! struct MySubscriptionHandler;
//!
//! #[async_trait::async_trait]
//! impl SubscriptionHandler for MySubscriptionHandler {
//!     async fn on_subscription_created(&self, _event: &SubscriptionEvent) -> anyhow::Result<()> {
//!         Ok(())
//!     }
//!
//!     async fn on_subscription_updated(&self, _event: &SubscriptionEvent) -> anyhow::Result<()> {
//!         Ok(())
//!     }
//!
//!     async fn on_subscription_deleted(&self, _event: &SubscriptionEvent) -> anyhow::Result<()> {
//!         Ok(())
//!     }
//!
//!     async fn on_payment_succeeded(&self, _event: &InvoiceEvent) -> anyhow::Result<()> {
//!         Ok(())
//!     }
//!
//!     async fn on_payment_failed(&self, _event: &InvoiceEvent) -> anyhow::Result<()> {
//!         Ok(())
//!     }
//!
//!     async fn on_customer_created(&self, _event: &CustomerEvent) -> anyhow::Result<()> {
//!         Ok(())
//!     }
//! }
//! ```

pub mod config;
pub mod error;
pub mod events;
pub mod handler;
pub mod idempotency;
pub mod processor;
pub mod signature;

// Re-export commonly used items
pub use config::StripeWebhookConfig;
pub use error::{StripeWebhookError, StripeWebhookResult};
pub use events::{
    CustomerEvent, InvoiceEvent, StripeEvent, StripeEventType, SubscriptionEvent,
    SubscriptionStatus,
};
pub use handler::{stripe_webhook_handler, stripe_webhook_router, StripeWebhookState};
pub use idempotency::{IdempotencyStore, InMemoryIdempotencyStore};
pub use processor::{EventProcessor, SubscriptionHandler};
pub use signature::SignatureVerifier;