atp-client 0.1.0

Framework-neutral ATP billing SDK with optional Axum routes, guards, caching, and JWT claims enrichment
Documentation

atp-client

Framework-neutral Rust SDK for integrating an application backend with ATP billing. It deliberately does not depend on ATP backend internals, AWS SDKs, Stripe SDKs, or a particular authentication provider.

atp-client = "0.1"
# Non-Axum applications:
# atp-client = { version = "0.1", default-features = false }

Client

use atp_client::{AtpClient, DebitRequest};
use secrecy::SecretString;

# async fn example() -> atp_client::SdkResult<()> {
let atp = AtpClient::new(
    "https://atp.example.com",
    SecretString::from(std::env::var("ATP_API_KEY").expect("ATP_API_KEY")),
)?;

let status = atp.status("user_123").await?;
if status.balance.total() >= 2 {
    let result = atp.debit(
        &DebitRequest {
            user_id: "user_123".into(),
            amount: 2,
            related_id: "generation_456".into(),
            description: Some("image generation".into()),
        },
        "generation-456", // reuse this key when retrying the same work
    ).await?;
    println!("charged as {}", result.tx_id);
}
# Ok(())
# }

The client automatically retries bounded GET failures only. It never retries debit, refund, or Checkout writes; callers decide their retry window and reuse a stable business idempotency key.

Caching and outage semantics

CachedBillingClient keeps a bounded process-local status cache and coalesces concurrent misses for the same user. Its explicit policies are:

  • FailClosed: authorization default; an ATP outage denies access.
  • UseStale: recently expired state may be shown in UI, marked degraded.
  • FreeTier: login can continue with zero-credit Free claims, marked degraded.

Debit/refund results are never cached. A successful balance-changing operation invalidates the user's status. A cache instance belongs to one tenant API key and must not be shared across tenants.

Existing authentication and JWTs

ClaimsEnricher adds a versioned atp namespace after your application authenticates the user and before its existing signer creates the JWT. The SDK does not verify tokens, own signing keys, or mutate already-signed identity-provider tokens.

Tier and credits inside a JWT are issue-time snapshots. Keep locally issued session tokens short-lived; use request-level status for sensitive authorization, and always use ATP debit for concurrency-safe credit consumption.

Axum integration

The default axum feature provides:

  • BillingRouter with same-origin status, balance, history, Checkout, and Portal endpoints;
  • ExtensionBillingUserResolver<T> to reuse a Principal inserted by existing auth middleware;
  • BillingContext, require_tier, and require_credits route guards.

Checkout/Portal identity comes from the authenticated Principal, never browser JSON. The application's authentication layer must remain outermost. Credit guards are an early UX/authorization check and do not reserve credits; charged handlers still call debit.

See the complete API documentation on docs.rs.

See the integration guide and OpenAPI contract.