Skip to main content
Coming Soon: Extensions are not currently available. This feature is under development and will be released soon.

​
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

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