agentbill-sdk 2.0.1 → 7.17.0

data/lib/agentbill/orders.rb

@@ -0,0 +1,283 @@
+# AgentBill Orders Resource - CRUD operations with line items
+# 
+# IMPORTANT: At least one agent must be associated with an order via
+# agent_ids or agent_external_ids. Orders cannot be created without agents.
+#
+# Example:
+#   ab = AgentBill::Client.init(api_key: 'agb_...')
+#   
+#   # List orders
+#   result = ab.orders.list(limit: 10)
+#   
+#   # Create order (agent_ids or agent_external_ids REQUIRED)
+#   order = ab.orders.create(
+#     account_id: 'acct-123',
+#     name: 'Enterprise Q1',
+#     agent_ids: ['agent-uuid-1']  # REQUIRED
+#   )
+#   
+#   # Add line item
+#   ab.orders.add_line_item(
+#     order_id: order['id'],
+#     description: 'AI Usage',
+#     quantity: 1000,
+#     unit_price: 0.05,
+#     item_type: 'usage'
+#   )
+#   
+#   # Get order by ID
+#   order = ab.orders.get('order-123')
+#   
+#   # Update order
+#   order = ab.orders.update('order-123', status: 'active')
+#   
+#   # Delete order
+#   ab.orders.delete('order-123')
+
+require 'net/http'
+require 'json'
+
+module AgentBill
+  # Valid item_type values for add_line_item:
+  # - usage: Variable consumption billing (API calls, tokens, requests)
+  # - platform_fee: Platform access and service charges
+  # - setup_fee: One-time onboarding and implementation costs
+  # - base_fee: Fixed recurring monthly/annual charges
+  # - overage: Usage exceeding included plan amounts
+  # - custom: Flexible billing for unique scenarios
+  # - flat_rate: Fixed-price service packages or retainers
+  # - product: Physical or digital product sales
+  # - service: Professional services and consulting
+  # - subscription: Recurring subscription billing
+  VALID_ITEM_TYPES = %w[usage platform_fee setup_fee base_fee overage custom product service subscription flat_rate].freeze
+
+  class OrdersResource
+    def initialize(config)
+      @config = config
+      @base_url = config[:base_url] || 'https://api.agentbill.io'
+      @api_key = config[:api_key]
+      @debug = config[:debug] || false
+    end
+
+    # List orders with pagination and filtering
+    #
+    # @param account_id [String, nil] Filter by account ID
+    # @param status [String, nil] Filter by status (draft, active, completed, cancelled)
+    # @param limit [Integer] Number of orders to return (default: 50)
+    # @param offset [Integer] Offset for pagination (default: 0)
+    # @param search [String, nil] Search term to filter by name or external_id
+    # @return [Hash] Hash with 'data' (list of orders) and 'pagination' info
+    def list(account_id: nil, status: nil, limit: 50, offset: 0, search: nil)
+      uri = URI("#{@base_url}/functions/v1/api-orders")
+      params = { limit: limit.to_s, offset: offset.to_s }
+      params[:search] = search if search
+      params[:account_id] = account_id if account_id
+      params[:status] = status if status
+      uri.query = URI.encode_www_form(params)
+
+      response = make_request(:get, uri)
+      handle_response(response, 'list orders')
+    end
+
+    # Create a new order
+    #
+    # IMPORTANT: At least one agent must be specified via agent_ids or agent_external_ids.
+    # Orders cannot be created without agent association for proper billing attribution.
+    #
+    # @param account_id [String] Account (customer) UUID (required unless account_external_id provided)
+    # @param name [String] Order name (required)
+    # @param agent_ids [Array<String>, nil] List of agent UUIDs (required if agent_external_ids not provided)
+    # @param agent_external_ids [Array<String>, nil] List of agent external IDs (required if agent_ids not provided)
+    # @param external_id [String, nil] Your external ID for this order
+    # @param account_external_id [String, nil] External ID of the account
+    # @param billing_contact_id [String, nil] Contact UUID for billing
+    # @param billing_contact_external_id [String, nil] External ID of billing contact
+    # @param start_date [String, nil] Order start date (ISO format)
+    # @param end_date [String, nil] Order end date (ISO format)
+    # @param status [String, nil] Order status (draft, active, completed, cancelled)
+    # @param currency [String, nil] Currency code (default: USD)
+    # @param metadata [Hash, nil] Additional metadata
+    # @return [Hash] Created order object
+    # @raise [ArgumentError] If neither agent_ids nor agent_external_ids provided
+    def create(account_id:, name:, agent_ids: nil, agent_external_ids: nil, external_id: nil,
+               account_external_id: nil, billing_contact_id: nil, billing_contact_external_id: nil,
+               start_date: nil, end_date: nil, status: nil, currency: nil, metadata: nil)
+      # Validate agent requirement
+      if (agent_ids.nil? || agent_ids.empty?) && (agent_external_ids.nil? || agent_external_ids.empty?)
+        raise ArgumentError, 'At least one agent must be specified via agent_ids or agent_external_ids. ' \
+                             'Orders cannot be created without agent association for billing attribution.'
+      end
+
+      uri = URI("#{@base_url}/functions/v1/api-orders")
+      
+      payload = { account_id: account_id, name: name }
+      payload[:agent_ids] = agent_ids if agent_ids&.any?
+      payload[:agent_external_ids] = agent_external_ids if agent_external_ids&.any?
+      payload[:external_id] = external_id if external_id
+      payload[:account_external_id] = account_external_id if account_external_id
+      payload[:billing_contact_id] = billing_contact_id if billing_contact_id
+      payload[:billing_contact_external_id] = billing_contact_external_id if billing_contact_external_id
+      payload[:start_date] = start_date if start_date
+      payload[:end_date] = end_date if end_date
+      payload[:status] = status if status
+      payload[:currency] = currency if currency
+      payload[:metadata] = metadata if metadata
+
+      response = make_request(:post, uri, payload)
+      handle_response(response, 'create order')
+    end
+
+    # Get an order by ID or external_id (includes line items)
+    #
+    # @param order_id [String] Order UUID or external_id
+    # @param by_external_id [Boolean] If true, treat order_id as external_id
+    # @return [Hash] Order object with order_line_items
+    def get(order_id, by_external_id: false)
+      uri = URI("#{@base_url}/functions/v1/api-orders")
+      params = by_external_id ? { external_id: order_id } : { id: order_id }
+      uri.query = URI.encode_www_form(params)
+
+      response = make_request(:get, uri)
+      handle_response(response, 'get order')
+    end
+
+    # Update an order
+    #
+    # @param order_id [String] Order UUID
+    # @param name [String, nil] New name
+    # @param billing_contact_id [String, nil] New billing contact ID
+    # @param start_date [String, nil] New start date
+    # @param end_date [String, nil] New end date
+    # @param status [String, nil] New status
+    # @param currency [String, nil] New currency
+    # @param metadata [Hash, nil] New metadata (replaces existing)
+    # @return [Hash] Updated order object
+    def update(order_id, name: nil, billing_contact_id: nil, start_date: nil, 
+               end_date: nil, status: nil, currency: nil, metadata: nil)
+      uri = URI("#{@base_url}/functions/v1/api-orders")
+      
+      payload = { id: order_id }
+      payload[:name] = name if name
+      payload[:billing_contact_id] = billing_contact_id if billing_contact_id
+      payload[:start_date] = start_date if start_date
+      payload[:end_date] = end_date if end_date
+      payload[:status] = status if status
+      payload[:currency] = currency if currency
+      payload[:metadata] = metadata if metadata
+
+      response = make_request(:patch, uri, payload)
+      handle_response(response, 'update order')
+    end
+
+    # Delete an order and its line items
+    #
+    # @param order_id [String] Order UUID to delete
+    def delete(order_id)
+      uri = URI("#{@base_url}/functions/v1/api-orders")
+      payload = { id: order_id }
+
+      response = make_request(:delete, uri, payload)
+      handle_response(response, 'delete order')
+    end
+
+    # Add a line item to an order
+    #
+    # @param order_id [String] Order UUID (required)
+    # @param description [String] Line item description (required)
+    # @param quantity [Numeric] Quantity (required)
+    # @param unit_price [Numeric] Price per unit (required)
+    # @param product_id [String, nil] Product reference ID
+    # @param product_name [String, nil] Product name
+    # @param product_sku [String, nil] Product SKU
+    # @param usage_metric [String, nil] Usage metric name
+    # @param usage_quantity [Numeric, nil] Usage quantity
+    # @param discount_type [String, nil] "percentage" or "fixed"
+    # @param discount_value [Numeric, nil] Discount amount/percentage
+    # @param tax_rate [Numeric, nil] Tax rate percentage
+    # @param notes [String, nil] Additional notes
+    # @param sort_order [Integer, nil] Display order
+    # @param agent_id [String, nil] Associated agent ID
+    # @param item_type [String, nil] Type: usage, platform_fee, setup_fee, base_fee, overage, custom, product, service, subscription
+    # @param metadata [Hash, nil] Additional metadata
+    # @return [Hash] Created line item object
+    def add_line_item(order_id:, description:, quantity:, unit_price:, product_id: nil, 
+                      product_name: nil, product_sku: nil, usage_metric: nil, usage_quantity: nil,
+                      discount_type: nil, discount_value: nil, tax_rate: nil, notes: nil,
+                      sort_order: nil, agent_id: nil, item_type: nil, metadata: nil)
+      uri = URI("#{@base_url}/functions/v1/api-orders?action=line-items")
+      
+      payload = {
+        order_id: order_id,
+        description: description,
+        quantity: quantity,
+        unit_price: unit_price
+      }
+      payload[:product_id] = product_id if product_id
+      payload[:product_name] = product_name if product_name
+      payload[:product_sku] = product_sku if product_sku
+      payload[:usage_metric] = usage_metric if usage_metric
+      payload[:usage_quantity] = usage_quantity if usage_quantity
+      payload[:discount_type] = discount_type if discount_type
+      payload[:discount_value] = discount_value if discount_value
+      payload[:tax_rate] = tax_rate if tax_rate
+      payload[:notes] = notes if notes
+      payload[:sort_order] = sort_order if sort_order
+      payload[:agent_id] = agent_id if agent_id
+      payload[:item_type] = item_type if item_type
+      payload[:metadata] = metadata if metadata
+
+      response = make_request(:post, uri, payload)
+      handle_response(response, 'add line item')
+    end
+
+    # Remove a line item from an order
+    #
+    # @param line_item_id [String] Line item UUID to delete
+    def remove_line_item(line_item_id)
+      uri = URI("#{@base_url}/functions/v1/api-orders?action=line-items")
+      payload = { id: line_item_id }
+
+      response = make_request(:delete, uri, payload)
+      handle_response(response, 'remove line item')
+    end
+
+    private
+
+    def make_request(method, uri, payload = nil)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.read_timeout = 30
+
+      case method
+      when :get
+        request = Net::HTTP::Get.new(uri)
+      when :post
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request.body = payload.to_json if payload
+      when :patch
+        request = Net::HTTP::Patch.new(uri.path)
+        request.body = payload.to_json if payload
+      when :delete
+        request = Net::HTTP::Delete.new(uri.request_uri)
+        request.body = payload.to_json if payload
+      end
+
+      request['Content-Type'] = 'application/json'
+      request['X-API-Key'] = @api_key
+
+      http.request(request)
+    end
+
+    def handle_response(response, operation)
+      body = response.body ? JSON.parse(response.body) : {}
+      
+      unless %w[200 201 204].include?(response.code)
+        error_msg = body['error'] || "Failed to #{operation}"
+        raise error_msg
+      end
+
+      puts "[AgentBill] #{operation} successful" if @debug
+      body
+    end
+  end
+end

data/lib/agentbill/perplexity_wrapper.rb

@@ -0,0 +1,101 @@
+# Perplexity AI Wrapper for AgentBill Ruby SDK
+require_relative 'pricing'
+
+module AgentBill
+  class PerplexityWrapper
+    def initialize(client, config, tracer)
+      @client = client
+      @config = config
+      @tracer = tracer
+    end
+
+    def wrap
+      original_chat_create = @client.method(:chat_create)
+      config = @config
+      tracer = @tracer
+
+      @client.define_singleton_method(:chat_create) do |params|
+        model = params[:model] || 'llama-3.1-sonar-small-128k-online'
+        messages = params[:messages] || []
+
+        start_time = Time.now
+        span = tracer.start_span('perplexity.chat.completions.create', {
+          # ✅ OTEL GenAI compliant attributes
+          'gen_ai.system' => 'perplexity',
+          'gen_ai.request.model' => model,
+          'gen_ai.operation.name' => 'chat',
+          # ⚠️ Backward compatibility
+          'model' => model,
+          'provider' => 'perplexity'
+        })
+
+        begin
+          response = original_chat_create.call(params)
+          latency = ((Time.now - start_time) * 1000).round
+
+          input_tokens = response.dig(:usage, :prompt_tokens) || 0
+          output_tokens = response.dig(:usage, :completion_tokens) || 0
+          cost = Pricing.calculate_cost(model, input_tokens, output_tokens, 'perplexity')
+
+          track_usage(model, 'perplexity', input_tokens, output_tokens, latency, cost, config)
+
+          span.set_attributes({
+            # ✅ OTEL GenAI compliant attributes
+            'gen_ai.usage.input_tokens' => input_tokens,
+            'gen_ai.usage.output_tokens' => output_tokens,
+            'gen_ai.response.id' => response.dig(:id),
+            # ⚠️ Backward compatibility
+            'response.prompt_tokens' => input_tokens,
+            'response.completion_tokens' => output_tokens,
+            'latency_ms' => latency,
+            'cost' => cost
+          })
+          span.set_status(0)
+
+          puts "[AgentBill] ✓ Perplexity chat tracked: $#{format('%.6f', cost)}" if config[:debug]
+          response
+        rescue => e
+          span.set_status(1, e.message)
+          raise
+        ensure
+          span.finish
+        end
+      end
+
+      @client
+    end
+
+    private
+
+    def track_usage(model, provider, input_tokens, output_tokens, latency, cost, config)
+      uri = URI("#{config[:base_url] || 'https://api.agentbill.io'}/functions/v1/track-ai-usage")
+
+      payload = {
+        api_key: config[:api_key],
+        customer_id: config[:customer_id],
+        agent_id: config[:agent_id],
+        event_name: 'ai_request',
+        model: model,
+        provider: provider,
+        prompt_tokens: input_tokens,
+        completion_tokens: output_tokens,
+        latency_ms: latency,
+        cost: cost
+      }
+
+      begin
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(uri.path)
+        request['Content-Type'] = 'application/json'
+        request.body = payload.to_json
+
+        http.request(request)
+      rescue => e
+        puts "[AgentBill] Tracking failed: #{e.message}" if config[:debug]
+      end
+    end
+  end
+end

data/lib/agentbill/pricing.rb

@@ -0,0 +1,52 @@
+# AgentBill SDK Pricing - LOCAL ESTIMATION ONLY
+#
+# IMPORTANT: Cost calculation is now 100% SERVER-SIDE
+# The server uses the model_pricing database table (synced by sync-model-pricing).
+# This module is kept ONLY for local estimation/display purposes.
+# The AUTHORITATIVE cost is always calculated server-side.
+
+module AgentBill
+  module Pricing
+    # Default fallback rates for local estimation only
+    DEFAULT_INPUT_PER_1M = 1.0
+    DEFAULT_OUTPUT_PER_1M = 2.0
+
+    class << self
+      # LOCAL ESTIMATION ONLY - for display purposes.
+      # Actual cost is calculated server-side using model_pricing database.
+      def calculate_cost(model, input_tokens, output_tokens, provider = 'openai')
+        # Ollama is free
+        return 0.0 if provider == 'ollama' || model.to_s.start_with?('ollama/')
+
+        # Simple default estimate - server calculates actual cost
+        input_cost = (input_tokens.to_f / 1_000_000) * DEFAULT_INPUT_PER_1M
+        output_cost = (output_tokens.to_f / 1_000_000) * DEFAULT_OUTPUT_PER_1M
+        input_cost + output_cost
+      end
+
+      # LOCAL ESTIMATION ONLY for image generation
+      def calculate_image_cost(model, size, quality = 'standard')
+        if model.include?('dall-e-3')
+          quality == 'hd' ? 0.08 : 0.04
+        else
+          0.02
+        end
+      end
+
+      # LOCAL ESTIMATION ONLY for audio
+      def calculate_audio_cost(model, duration_seconds: 0, chars: 0)
+        if model == 'whisper-1'
+          (duration_seconds.to_f / 60.0) * 0.006
+        elsif model.start_with?('tts-')
+          (chars.to_f / 1_000_000) * 15.0
+        else
+          0.0
+        end
+      end
+
+      def embedding_model?(model)
+        model.downcase.include?('embedding') || model.downcase.include?('embed')
+      end
+    end
+  end
+end

data/lib/agentbill/signal_types.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module AgentBill
+  # Signal Types Resource - CRUD operations for signal type management
+  # v7.15.0: New resource for programmatic signal type management
+  #
+  # @example
+  #   client = AgentBill::Client.new(api_key: 'agb_...')
+  #   
+  #   # Create signal type
+  #   st = client.signal_types.create(name: 'ai_completion', category: 'activity')
+  #   
+  #   # List all
+  #   signal_types = client.signal_types.list
+  #   
+  #   # Get by ID
+  #   st = client.signal_types.get(signal_type_id)
+  #   
+  #   # Update
+  #   client.signal_types.update(signal_type_id, description: 'Updated')
+  #   
+  #   # Delete
+  #   client.signal_types.delete(signal_type_id)
+  #
+  class SignalTypesResource
+    def initialize(config)
+      @base_url = config[:base_url] || 'https://api.agentbill.io'
+      @api_key = config[:api_key]
+      @debug = config[:debug] || false
+    end
+
+    # List signal types with optional filters
+    #
+    # @param category [String, nil] Filter by category ('activity' or 'outcome')
+    # @param include_global [Boolean] Include global signal types (default: true)
+    # @return [Hash] Response with :data array and :summary
+    def list(category: nil, include_global: true)
+      uri = URI("#{@base_url}/functions/v1/api-signal-types")
+      params = {}
+      params[:category] = category if category
+      params[:include_global] = 'false' unless include_global
+      uri.query = URI.encode_www_form(params) unless params.empty?
+
+      response = make_request(:get, uri)
+      handle_response(response, 'list signal types')
+    end
+
+    # Create a new signal type
+    #
+    # @param name [String] Signal type name (required)
+    # @param category [String] Category - 'activity' or 'outcome' (default: 'activity')
+    # @param description [String, nil] Description
+    # @param unit [String, nil] Unit of measurement
+    # @param default_value [Float, nil] Default value
+    # @param external_id [String, nil] Your external ID
+    # @param expected_metrics [Hash, nil] Expected metrics configuration
+    # @param revenue_formula [String, nil] Revenue formula
+    # @param validation_rules [Hash, nil] Validation rules
+    # @return [Hash] Created signal type
+    def create(name:, category: 'activity', description: nil, unit: nil, default_value: nil,
+               external_id: nil, expected_metrics: nil, revenue_formula: nil, validation_rules: nil)
+      payload = { name: name, category: category }
+      payload[:description] = description if description
+      payload[:unit] = unit if unit
+      payload[:default_value] = default_value if default_value
+      payload[:external_id] = external_id if external_id
+      payload[:expected_metrics] = expected_metrics if expected_metrics
+      payload[:revenue_formula] = revenue_formula if revenue_formula
+      payload[:validation_rules] = validation_rules if validation_rules
+
+      uri = URI("#{@base_url}/functions/v1/api-signal-types")
+      response = make_request(:post, uri, payload)
+      handle_response(response, 'create signal type')
+    end
+
+    # Get a signal type by ID or external_id
+    #
+    # @param signal_type_id [String] Signal type UUID or external_id
+    # @param by_external_id [Boolean] If true, treat signal_type_id as external_id
+    # @return [Hash] Signal type object
+    def get(signal_type_id, by_external_id: false)
+      uri = URI("#{@base_url}/functions/v1/api-signal-types")
+      param = by_external_id ? :external_id : :id
+      uri.query = URI.encode_www_form({ param => signal_type_id })
+
+      response = make_request(:get, uri)
+      handle_response(response, 'get signal type')
+    end
+
+    # Update a signal type
+    #
+    # @param signal_type_id [String] Signal type UUID
+    # @param name [String, nil] New name
+    # @param description [String, nil] New description
+    # @param category [String, nil] New category
+    # @param unit [String, nil] New unit
+    # @param default_value [Float, nil] New default value
+    # @param external_id [String, nil] New external ID
+    # @param expected_metrics [Hash, nil] New expected metrics
+    # @param revenue_formula [String, nil] New revenue formula
+    # @param validation_rules [Hash, nil] New validation rules
+    # @param is_active [Boolean, nil] Active status
+    # @return [Hash] Updated signal type
+    def update(signal_type_id, name: nil, description: nil, category: nil, unit: nil,
+               default_value: nil, external_id: nil, expected_metrics: nil,
+               revenue_formula: nil, validation_rules: nil, is_active: nil)
+      payload = { id: signal_type_id }
+      payload[:name] = name if name
+      payload[:description] = description if description
+      payload[:category] = category if category
+      payload[:unit] = unit if unit
+      payload[:default_value] = default_value if default_value
+      payload[:external_id] = external_id if external_id
+      payload[:expected_metrics] = expected_metrics if expected_metrics
+      payload[:revenue_formula] = revenue_formula if revenue_formula
+      payload[:validation_rules] = validation_rules if validation_rules
+      payload[:is_active] = is_active unless is_active.nil?
+
+      uri = URI("#{@base_url}/functions/v1/api-signal-types")
+      response = make_request(:patch, uri, payload)
+      handle_response(response, 'update signal type')
+    end
+
+    # Delete a signal type
+    #
+    # @param signal_type_id [String] Signal type UUID to delete
+    # @return [Hash] Deletion result
+    def delete(signal_type_id)
+      uri = URI("#{@base_url}/functions/v1/api-signal-types")
+      response = make_request(:delete, uri, { id: signal_type_id })
+      handle_response(response, 'delete signal type')
+    end
+
+    private
+
+    def make_request(method, uri, payload = nil)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      request = case method
+                when :get
+                  Net::HTTP::Get.new(uri)
+                when :post
+                  Net::HTTP::Post.new(uri)
+                when :patch
+                  Net::HTTP::Patch.new(uri)
+                when :delete
+                  Net::HTTP::Delete.new(uri)
+                end
+
+      request['Content-Type'] = 'application/json'
+      request['X-API-Key'] = @api_key
+      request.body = payload.to_json if payload
+
+      puts "[AgentBill] #{method.upcase} #{uri}" if @debug
+
+      http.request(request)
+    end
+
+    def handle_response(response, operation)
+      body = response.body ? JSON.parse(response.body) : {}
+
+      case response.code.to_i
+      when 200, 201, 204
+        body
+      when 404
+        raise "Signal type not found"
+      when 409
+        raise "Signal type already exists: #{body['error']}"
+      else
+        raise "Failed to #{operation}: #{body['error'] || response.body}"
+      end
+    end
+  end
+end