> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valmi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How valext Works

> Understanding the valext extension protocol

<Warning>
  **Coming Soon**: Extensions are not currently available. This feature is under development and will be released soon.
</Warning>

## valext Protocol

valext is an open-source extension protocol that defines how extensions interact with Valmi Value and external systems.

> **Note**: The extension system is currently under development. The information below is a preview of what will be available.

## Event-Driven Architecture

Extensions are event-driven and react to events from Valmi Value:

### Event Types

* `invoice.created` - New invoice generated
* `invoice.paid` - Invoice payment received
* `outcome.completed` - Business outcome achieved
* `subscription.created` - New subscription
* `subscription.updated` - Subscription changed
* `payment.successful` - Payment processed

### Event Payload

Events include:

* **Event Type**: What happened
* **Timestamp**: When it happened
* **Data**: Event-specific data
* **Metadata**: Additional context

## Extension Lifecycle

### 1. Registration

Extensions register with Valmi Value:

* Provide extension metadata
* Subscribe to event types
* Configure authentication

### 2. Event Reception

When events occur:

* Valmi Value sends event to extension
* Extension receives event via webhook or polling
* Extension validates event authenticity

### 3. Processing

Extension processes event:

* Transforms data to external system format
* Calls external system API
* Handles errors and retries

### 4. Response

Extension reports result:

* Success: Event processed successfully
* Failure: Error occurred (with retry)
* Status: Processing status updates

## Metadata Contracts

Extensions use standardized metadata formats:

### Invoice Metadata

```json theme={null}
{
  "invoice_id": "inv_abc123",
  "account_id": "account_xyz789",
  "amount": 1000.00,
  "currency": "USD",
  "line_items": [...],
  "due_date": "2024-02-15"
}
```

### Payment Metadata

```json theme={null}
{
  "payment_id": "pay_abc123",
  "invoice_id": "inv_xyz789",
  "amount": 1000.00,
  "currency": "USD",
  "payment_method": "stripe",
  "transaction_id": "txn_123"
}
```

## Mapping to Upstream Systems

Extensions map Valmi Value data to external system formats:

### Stripe Mapping

```python theme={null}
def map_to_stripe(invoice):
    return {
        "amount": int(invoice.amount * 100),  # Convert to cents
        "currency": invoice.currency.lower(),
        "customer": invoice.account.stripe_customer_id,
        "metadata": {
            "valmi_invoice_id": invoice.id
        }
    }
```

### QuickBooks Mapping

```python theme={null}
def map_to_quickbooks(invoice):
    return {
        "Line": [
            {
                "Amount": invoice.amount,
                "DetailType": "SalesItemLineDetail",
                "SalesItemLineDetail": {
                    "ItemRef": {"value": "1"}
                }
            }
        ],
        "CustomerRef": {"value": invoice.account.quickbooks_id}
    }
```

## Error Handling

Extensions handle errors gracefully:

* **Retries**: Automatic retry with exponential backoff
* **Dead Letter Queue**: Failed events stored for manual review
* **Notifications**: Alert on persistent failures
* **Logging**: Comprehensive error logging

## Extension Configuration

Extensions are configured per account or globally:

* **API Keys**: External system credentials
* **Mapping Rules**: How to transform data
* **Retry Policies**: How to handle failures
* **Filters**: Which events to process