Usage Guide

from nekuda import MandateData, NekudaClient, NekudaError
import os

# Initialize client - uses NEKUDA_API_KEY from environment by default.
# Default base_url is https://api.nekuda.ai
client = NekudaClient.from_env()

# Or with explicit config (not needed if NEKUDA_API_KEY is set):
# client = NekudaClient(
#     api_key="sk_live_your_api_key",
#     # base_url="https://api.nekuda.ai", # Default, no need to specify for production
#     timeout=30,
#     max_retries=3
# )

# 1️⃣ Provide a unique user_id for your end-user.
user_id = "user_integration_test_123"
user = client.user(user_id)

try:
    # 2️⃣ Create a mandate (describes the purchase intent)
    mandate = MandateData(
        product="Premium Gold Subscription",
        price=99.99,
        currency="USD",
        merchant="nekuda Demo Store",
        merchant_link="https://app.nekuda.ai/demostore",
        product_description="Monthly access to all gold features"
    )

    # The user_id (user_integration_test_123) is implicitly passed.
    mandate_response = user.create_mandate(mandate)

    # Type-safe access to all fields!
    print(f"✅ Mandate Created: {mandate_response.mandate_id} for user: {user_id}")
    print(f"   Request ID: {mandate_response.request_id}")
    print(f"   Created At: {mandate_response.created_at}")

    # 3️⃣ Request reveal token using the mandate_id from the previous step.
    reveal_response = user.request_card_reveal_token(
        mandate_id=mandate_response.mandate_id  # Can use int or string
    )

    print(f"🔑 Reveal Token Generated: {reveal_response.reveal_token[:20]}...")
    print(f"   API Path for Reveal: {reveal_response.reveal_path}")

    # Check expiration if available
    if reveal_response.expires_at:
        print(f"   Token expires at: {reveal_response.expires_at}")

    # 4️⃣ Reveal card details using the single-use reveal_token.
    # The user_id is also implicitly passed here.
    card = user.reveal_card_details(reveal_response.reveal_token)

    # All fields are typed and validated!
    print(f"💳 Card Revealed: **** **** **** {card.card_number[-4:]}")
    print(f"   Expiry: {card.card_expiry_date}")  # Guaranteed MM/YY format
    print(f"   Name: {card.cardholder_name}")

    # Optional fields are properly typed
    if card.email:
        print(f"   Email: {card.email}")
    if card.billing_address:
        print(f"   Address: {card.billing_address}")

    print("🎉 Successfully completed the card reveal flow!")

except NekudaError as e:
    # Structured error handling
    print(f"❌ An error occurred: {e}")
    if hasattr(e, 'status_code'):
        print(f"   HTTP Status: {e.status_code}")
    if hasattr(e, 'code'):
        print(f"   Error Code: {e.code}")
    # For more details on error handling, see the Errors guide.