code-documenter

def process_payment(user_id, amount, currency, idempotency_key=None):
    user = db.users.find(user_id)
    if not user:
        raise ValueError("User not found")
    if user.balance < amount and not user.credit_enabled:
        return {"status": "declined", "reason": "insufficient_funds"}
    charge = stripe.charges.create(
        amount=int(amount * 100),
        currency=currency,
        customer=user.stripe_id,
        idempotency_key=idempotency_key
    )
    db.transactions.insert({
        "user_id": user_id, "amount": amount,
        "stripe_charge_id": charge.id, "created_at": datetime.utcnow()
    })
    if user.balance < amount:
        user.balance = user.balance - amount
        db.users.update(user)
    return {"status": "success", "charge_id": charge.id}

def process_payment(user_id, amount, currency, idempotency_key=None):
    """Process a payment by charging the user's Stripe account.

    Validates the user's balance (unless credit is enabled), creates a Stripe
    charge, records the transaction, and deducts from the user's internal balance
    if applicable.

    Args:
        user_id: Internal user identifier (e.g., "usr_8f2k3j").
        amount: Charge amount in major currency units (e.g., 49.99).
        currency: ISO 4217 currency code (e.g., "usd", "eur").
        idempotency_key: Optional key to prevent duplicate charges on retry.
            Recommended for all production calls.

    Returns:
        dict: {"status": "success", "charge_id": "ch_..."} on success,
              {"status": "declined", "reason": "insufficient_funds"} if balance
              is too low and credit is not enabled.

    Raises:
        ValueError: If user_id does not match any user in the database.
        stripe.error.CardError: If the card is declined by Stripe.
        stripe.error.InvalidRequestError: If Stripe parameters are invalid.

    Side Effects:
        - Creates a Stripe charge (external API call)
        - Inserts a row into the transactions table
        - May update the user's balance

    Example:
        >>> result = process_payment("usr_8f2k3j", 49.99, "usd", idempotency_key="pay_retry_001")
        >>> result
        {"status": "success", "charge_id": "ch_3Kx9mPqR2s"}

    Note:
        ⚠ Potential bug: balance deduction only happens when balance < amount,
        but the charge always goes through. If balance >= amount, the user is
        charged via Stripe but their internal balance is not deducted.
    """

Document the architecture of our notification service in src/services/notifications/

# Notification Service — Architecture

## Purpose
Delivers user notifications across email, push, and in-app channels.
Handles template rendering, delivery scheduling, preference checking,
and delivery status tracking.

## Module Map
  notifications/
  ├── router.ts          — HTTP endpoints for notification preferences and history
  ├── service.ts         — Core orchestration: resolves channel, renders template, dispatches
  ├── channels/
  │   ├── email.ts       — SendGrid integration (SMTP fallback)
  │   ├── push.ts        — Firebase Cloud Messaging
  │   └── in-app.ts      — WebSocket broadcast + database persistence
  ├── templates/
  │   ├── renderer.ts    — Handlebars template engine with i18n support
  │   └── templates/     — .hbs files organized by notification type
  ├── preferences.ts     — User channel preferences (opt-in/opt-out per type)
  └── queue.ts           — Bull queue consumer for async delivery

## Key Data Flow: Sending a Notification
  1. API call or internal event → service.send(userId, type, data)
  2. service.ts checks user preferences → skips opted-out channels
  3. renderer.ts renders template with user's locale
  4. Dispatch queued via Bull (Redis-backed) for reliability
  5. Channel adapter delivers and records status in notifications table

## External Dependencies
  - SendGrid API (email delivery)
  - Firebase Cloud Messaging (push notifications)
  - Redis (Bull queue backing store)
  - PostgreSQL (notification history, preferences, templates metadata)

## Environment Variables
  SENDGRID_API_KEY, FCM_SERVER_KEY, REDIS_URL, NOTIFICATION_FROM_EMAIL