How valext Works

Understanding the valext extension protocol

valext Protocol

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

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

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

Payment Metadata

{
  "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

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

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