administrate-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf5605805daacbe02a2d9c84fba5cc4c3e6fa7b3d690087e80664b959a0c7c3d
+  data.tar.gz: 2053517211d59122b09bddf04f4c2cbd37cc8076cebfd2a6adf2d5362400ca32
+SHA512:
+  metadata.gz: eedd337177788041d4f65ef2a45ce183de4e7573e86057a0f323fc72c341825fb4205ad02516406a95d34ce4e8bd19a7fbf6f1315fea3eb7af25bf6582799522
+  data.tar.gz: dd2f7c9016e94de95a39e9d519e4ce97025eb18dd8368be029244e6973eb87872dbcc13ab891fee2b13af32e4bca496a0bdc8cc1d381038d381e57962552ea2d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Administrate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,493 @@
+# Administrate Ruby SDK
+
+The official Ruby SDK for the [Administrate.dev](https://administrate.dev) REST API.
+
+[Administrate.dev](https://administrate.dev) is AI Agency Management software. It is a monitoring and management platform for AI agencies running n8n and AI automation workflows across multiple clients. It provides a single dashboard to track every workflow, every client, every failure, and all LLM costs, so you can catch problems before clients do and prove the value of your automations.
+
+**Key platform features:**
+
+- **Multi-instance monitoring** -- See all n8n instances across every client in one place
+- **Error tracking** -- Real-time failure detection with automatic error categorization
+- **LLM cost tracking** -- Connect OpenAI, Anthropic, Azure, and OpenRouter accounts to attribute costs to specific clients
+- **Workflow insights** -- Execution counts, success rates, and time-saved ROI reporting
+- **Sync health** -- Know instantly when a data sync fails
+- **Webhooks & API** -- Full programmatic access for custom integrations
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'administrate-sdk'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install administrate-sdk
+```
+
+Requires Ruby 3.1+.
+
+## Quick start
+
+```ruby
+require 'administrate-sdk'
+
+client = Administrate.new(api_key: 'sk_live_...')
+
+# Get account info
+account = client.account.get
+puts "#{account.name} (#{account.plan})"
+
+# List all clients with auto-pagination
+client.clients.list.each do |c|
+  puts "#{c.name} (#{c.code})"
+end
+
+# Check for failed executions across all instances
+client.executions.list(errors_only: true).each do |execution|
+  puts "#{execution.workflow_name}: #{execution.error_category}"
+end
+
+# Get LLM cost summary
+costs = client.llm_costs.summary
+puts "Total: $#{'%.2f' % (costs.data.summary.total_cost_cents / 100.0)}"
+```
+
+## Configuration
+
+```ruby
+require 'administrate-sdk'
+
+client = Administrate.new(
+  api_key: 'sk_live_...',           # Required. Must start with "sk_live_"
+  base_url: 'https://...',          # Default: "https://administrate.dev"
+  timeout: 30,                      # Request timeout in seconds. Default: 30
+  max_retries: 3                    # Retry attempts for failed requests. Default: 3
+)
+```
+
+The SDK uses [Faraday](https://lostisland.github.io/faraday/) under the hood. Retry and backoff are handled automatically via the `faraday-retry` middleware.
+
+## API reference
+
+All API keys are created in **Settings > Developers** within Administrate.dev. Tokens have three permission levels: `read`, `write`, and `full`.
+
+### Account
+
+```ruby
+# Get current token info and account summary
+me = client.account.me
+puts "#{me.token.name} (#{me.token.permission})"
+puts "#{me.account.name} (#{me.account.plan})"
+
+# Get full account details
+account = client.account.get
+
+# Update account settings
+account = client.account.update(
+  name: 'My Agency',
+  billing_email: 'billing@example.com',
+  timezone: 'Australia/Brisbane'
+)
+```
+
+### Clients
+
+Clients represent the companies you manage automations for.
+
+```ruby
+# List all clients (auto-paginates)
+client.clients.list.each do |c|
+  puts "#{c.name} (#{c.code})"
+end
+
+# Get a client (includes 7-day metrics)
+c = client.clients.get('com_abc123')
+puts "#{c.metrics.success_rate}% success, #{c.metrics.time_saved_minutes} min saved"
+
+# Create a client
+c = client.clients.create(
+  name: 'Acme Corp',
+  code: 'acme',
+  contact_email: 'ops@acme.com',
+  timezone: 'America/New_York'
+)
+
+# Update a client
+c = client.clients.update('com_abc123', notes: 'Enterprise tier')
+
+# Delete a client (requires full permission)
+client.clients.delete('com_abc123')
+```
+
+### Instances
+
+Instances are n8n deployments connected to Administrate.
+
+```ruby
+# List all instances
+client.instances.list.each do |inst|
+  puts "#{inst.name} (#{inst.sync_status})"
+end
+
+# Filter by client or sync status
+client.instances.list(client_id: 'com_abc123', sync_status: 'error').each do |inst|
+  puts "#{inst.name}: #{inst.last_sync_error}"
+end
+
+# Get an instance (includes 7-day metrics)
+inst = client.instances.get('n8n_abc123')
+puts "#{inst.metrics.executions_count} executions, #{inst.metrics.success_rate}% success"
+
+# Connect a new n8n instance
+inst = client.instances.create(
+  client_id: 'com_abc123',
+  name: 'Production n8n',
+  base_url: 'https://n8n.acme.com',
+  api_key: 'n8n_api_key_here'
+)
+
+# Trigger a sync
+client.instances.sync('n8n_abc123', sync_type: 'all')
+
+# Sync all instances at once
+client.instances.sync_all(sync_type: 'workflows')
+
+# Update an instance
+inst = client.instances.update('n8n_abc123', name: 'Staging n8n')
+
+# Delete an instance
+client.instances.delete('n8n_abc123')
+```
+
+### Workflows
+
+```ruby
+# List workflows with filters
+client.workflows.list(client_id: 'com_abc123', active: true).each do |wf|
+  puts "#{wf.name} (active: #{wf.is_active})"
+end
+
+# Search by name
+client.workflows.list(search: 'onboarding').each do |wf|
+  puts wf.name
+end
+
+# Get a workflow (includes 7-day metrics)
+wf = client.workflows.get('wfl_abc123')
+puts "#{wf.metrics.success_rate}% success, #{wf.metrics.time_saved_minutes} min saved"
+
+# Set time-saved estimates (for ROI reporting)
+wf = client.workflows.update(
+  'wfl_abc123',
+  minutes_saved_per_success: 15,
+  minutes_saved_per_failure: 5
+)
+```
+
+### Executions
+
+Executions are read-only records of workflow runs synced from n8n.
+
+```ruby
+# List executions with filters
+client.executions.list(
+  client_id: 'com_abc123',
+  status: 'failed',
+  start_date: '2025-01-01',
+  end_date: '2025-01-31'
+).each do |ex|
+  puts "#{ex.workflow_name} - #{ex.status} (#{ex.duration_ms}ms)"
+end
+
+# Get only errors
+client.executions.list(errors_only: true).each do |ex|
+  puts "#{ex.error_category}: #{ex.workflow_name}"
+end
+
+# Get execution details (includes error message and payload)
+ex = client.executions.get('exe_abc123')
+puts ex.error_message
+puts ex.error_payload
+```
+
+### Sync runs
+
+```ruby
+# List sync run history
+client.sync_runs.list(instance_id: 'n8n_abc123', status: 'failed').each do |run|
+  puts "#{run.sync_type} - #{run.status} (#{run.duration_seconds}s)"
+end
+
+# Get a specific sync run
+run = client.sync_runs.get('syn_abc123')
+
+# Get sync health across all instances
+client.sync_runs.health.each do |entry|
+  puts "#{entry.instance_name} (#{entry.sync_status})"
+  puts "  Workflows last synced: #{entry.workflows.last_synced_at}"
+  puts "  Executions last synced: #{entry.executions.last_synced_at}"
+end
+```
+
+### Users
+
+```ruby
+# List team members
+client.users.list.each do |user|
+  puts "#{user.name} <#{user.email}> (#{user.role})"
+end
+
+# Get a user
+user = client.users.get('usr_abc123')
+
+# Invite a new team member
+invitation = client.users.invite(email: 'new@example.com', role: 'member')
+puts invitation.expires_at
+
+# Change a user's role
+user = client.users.update('usr_abc123', role: 'admin')
+
+# Remove a user
+client.users.delete('usr_abc123')
+```
+
+### Webhooks
+
+```ruby
+# List webhooks
+client.webhooks.list.each do |wh|
+  puts "#{wh.url} - #{wh.events.join(', ')} (enabled: #{wh.enabled})"
+end
+
+# Create a webhook
+wh = client.webhooks.create(
+  url: 'https://example.com/hook',
+  events: ['execution.failed', 'sync.failed'],
+  description: 'Slack failure alerts'
+)
+puts wh.secret  # Save this -- used to verify webhook signatures
+
+# Update a webhook
+wh = client.webhooks.update('whk_abc123', enabled: false)
+
+# Regenerate the signing secret (old secret becomes invalid immediately)
+wh = client.webhooks.regenerate_secret('whk_abc123')
+puts wh.secret
+
+# Delete a webhook
+client.webhooks.delete('whk_abc123')
+```
+
+### API tokens
+
+```ruby
+# List all tokens
+client.api_tokens.list.each do |token|
+  puts "#{token.name} (#{token.permission}) - #{token.token_hint}"
+end
+
+# Create a token (the plain token is only returned once)
+token = client.api_tokens.create(
+  name: 'CI/CD Pipeline',
+  permission: 'read',
+  ip_allowlist: ['10.0.0.0/8'],
+  expires_in: '90_days'
+)
+puts token.token  # sk_live_... -- save this immediately
+
+# Update a token
+token = client.api_tokens.update('tok_abc123', name: 'Updated Name')
+
+# Revoke a token
+client.api_tokens.delete('tok_abc123')
+```
+
+### LLM providers
+
+Connect your AI provider accounts to track costs.
+
+```ruby
+# List providers
+client.llm_providers.list.each do |provider|
+  puts "#{provider.name} (#{provider.provider_type}) - #{provider.sync_status}"
+end
+
+# Get a provider (includes 7-day metrics)
+provider = client.llm_providers.get('llm_abc123')
+puts "#{provider.metrics.total_cost_cents}c, #{provider.metrics.total_tokens} tokens"
+
+# Connect a new provider
+provider = client.llm_providers.create(
+  name: 'OpenAI Production',
+  provider_type: 'openai',  # openai, anthropic, openrouter, or azure
+  api_key: 'sk-...',
+  organization_id: 'org-...'
+)
+
+# Trigger a cost sync
+client.llm_providers.sync('llm_abc123')
+
+# Update a provider
+provider = client.llm_providers.update('llm_abc123', name: 'OpenAI Staging')
+
+# Delete a provider
+client.llm_providers.delete('llm_abc123')
+```
+
+### LLM projects
+
+Projects are discovered automatically when syncing a provider. Assign them to clients to attribute costs.
+
+```ruby
+# List projects for a provider
+client.llm_projects.list('llm_abc123').each do |project|
+  puts "#{project.name}: #{project.total_cost_cents}c (#{project.client_name})"
+end
+
+# Assign a project to a client
+project = client.llm_projects.update(
+  'llm_abc123', 'proj_456', client_id: 'com_abc123'
+)
+```
+
+### LLM costs
+
+```ruby
+# Get cost summary (defaults to last 7 days)
+costs = client.llm_costs.summary
+puts "Total: $#{'%.2f' % (costs.data.summary.total_cost_cents / 100.0)}"
+puts "Tokens: #{costs.data.summary.total_tokens}"
+
+# Breakdown by provider
+costs.data.providers.each do |p|
+  puts "  #{p.name}: $#{'%.2f' % (p.cost_cents / 100.0)}"
+end
+
+# Breakdown by model
+costs.data.models.each do |m|
+  puts "  #{m.model}: $#{'%.2f' % (m.cost_cents / 100.0)}"
+end
+
+# Daily trend
+costs.data.daily.each do |day|
+  puts "  #{day.date}: $#{'%.2f' % (day.cost_cents / 100.0)}"
+end
+
+# Custom date range
+costs = client.llm_costs.summary(
+  start_date: '2025-01-01',
+  end_date: '2025-01-31'
+)
+
+# Costs by client
+client.llm_costs.by_client.data.each do |entry|
+  puts "#{entry.name}: $#{'%.2f' % (entry.cost_cents / 100.0)}"
+end
+
+# Costs by provider
+client.llm_costs.by_provider.data.each do |entry|
+  puts "#{entry.name}: $#{'%.2f' % (entry.cost_cents / 100.0)}"
+end
+```
+
+## Pagination
+
+All `.list` methods return an `Enumerable` iterator that handles pagination automatically. By default, the API returns 25 items per page (max 100).
+
+```ruby
+# Auto-paginate through all results
+client.clients.list.each do |c|
+  puts c.name
+end
+
+# Control page size
+client.clients.list(per_page: 100).each do |c|
+  puts c.name
+end
+
+# Get a single page
+page = client.clients.list(per_page: 10).first_page
+puts "#{page.meta.total} total, #{page.meta.total_pages} pages"
+page.each do |c|
+  puts c.name
+end
+
+# Use any Enumerable method
+names = client.clients.list.map(&:name)
+active = client.workflows.list.select(&:is_active)
+first_five = client.users.list.first(5)
+```
+
+## Error handling
+
+The SDK raises typed exceptions for all API errors:
+
+```ruby
+require 'administrate-sdk'
+
+client = Administrate.new(api_key: 'sk_live_...')
+
+begin
+  c = client.clients.get('com_nonexistent')
+rescue Administrate::NotFoundError => e
+  puts "Not found: #{e.message}"
+rescue Administrate::AuthenticationError
+  puts 'Invalid API key'
+rescue Administrate::RateLimitError => e
+  puts "Rate limited. Retry after #{e.retry_after}s"
+rescue Administrate::ValidationError => e
+  puts "Invalid params: #{e.body}"
+rescue Administrate::APIError => e
+  puts "API error #{e.status_code}: #{e.message}"
+end
+```
+
+**Exception hierarchy:**
+
+| Exception | Status code | Description |
+|---|---|---|
+| `Administrate::Error` | -- | Base exception for all SDK errors |
+| `Administrate::APIError` | Any non-2xx | Base for all HTTP API errors |
+| `Administrate::AuthenticationError` | 401 | Invalid or missing API key |
+| `Administrate::PermissionDeniedError` | 403 | Insufficient token permissions |
+| `Administrate::NotFoundError` | 404 | Resource does not exist |
+| `Administrate::ValidationError` | 422 | Invalid request parameters |
+| `Administrate::RateLimitError` | 429 | Rate limit exceeded (has `retry_after`) |
+| `Administrate::InternalServerError` | 5xx | Server-side error |
+| `Administrate::ConnectionError` | -- | Failed to connect to the API |
+| `Administrate::TimeoutError` | -- | Request timed out |
+
+All `APIError` subclasses expose `status_code`, `response` (the raw Faraday response), and `body` (parsed JSON or text).
+
+## Retries
+
+The SDK automatically retries failed requests with exponential backoff:
+
+- **429 (rate limited)** -- Retries after the duration specified in the `Retry-After` header
+- **5xx (server errors)** -- Retries with exponential backoff (0.5s, 1s, 2s, ...)
+- **Connection errors and timeouts** -- Retried with the same backoff schedule
+
+By default, the SDK retries up to 3 times. Set `max_retries: 0` to disable:
+
+```ruby
+client = Administrate.new(api_key: 'sk_live_...', max_retries: 0)
+```
+
+## Requirements
+
+- Ruby 3.1+
+- [faraday](https://lostisland.github.io/faraday/) >= 2.0
+- [faraday-retry](https://github.com/lostisland/faraday-retry) >= 2.0
+
+## License
+
+MIT

data/lib/administrate/base_model.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Administrate
+  class BaseModel
+    class << self
+      def attribute(*names)
+        @attributes ||= []
+        names.each do |name|
+          @attributes << name.to_sym
+          attr_reader name
+        end
+      end
+
+      def nested(name, klass, array: false)
+        @nested_fields ||= {}
+        @nested_fields[name.to_sym] = { klass: klass, array: array }
+        attr_reader name
+      end
+
+      def attributes
+        @attributes || []
+      end
+
+      def nested_fields
+        @nested_fields || {}
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@attributes, (attributes || []).dup)
+        subclass.instance_variable_set(:@nested_fields, (nested_fields || {}).dup)
+      end
+    end
+
+    attr_reader :extra
+
+    def initialize(data = {})
+      data = data.transform_keys(&:to_sym) if data.is_a?(Hash)
+      known_keys = self.class.attributes + self.class.nested_fields.keys
+      @extra = {}
+
+      known_keys.each do |key|
+        value = data[key]
+        nested_config = self.class.nested_fields[key]
+
+        if nested_config && !value.nil?
+          value = if nested_config[:array]
+                    Array(value).map { |item| item.is_a?(Hash) ? nested_config[:klass].new(item) : item }
+                  elsif value.is_a?(Hash)
+                    nested_config[:klass].new(value)
+                  else
+                    value
+                  end
+        end
+
+        instance_variable_set(:"@#{key}", value)
+      end
+
+      data.each do |key, value|
+        @extra[key] = value unless known_keys.include?(key.to_sym)
+      end
+    end
+
+    def to_h
+      result = {}
+      (self.class.attributes + self.class.nested_fields.keys).each do |key|
+        value = instance_variable_get(:"@#{key}")
+        result[key] = serialize_value(value)
+      end
+      result.merge(@extra)
+    end
+
+    def [](key)
+      key = key.to_sym
+      if (self.class.attributes + self.class.nested_fields.keys).include?(key)
+        instance_variable_get(:"@#{key}")
+      else
+        @extra[key]
+      end
+    end
+
+    def ==(other)
+      return false unless other.is_a?(self.class)
+
+      to_h == other.to_h
+    end
+
+    def inspect
+      attrs = (self.class.attributes + self.class.nested_fields.keys).map do |key|
+        "#{key}=#{instance_variable_get(:"@#{key}").inspect}"
+      end
+      "#<#{self.class.name} #{attrs.join(', ')}>"
+    end
+
+    private
+
+    def serialize_value(value)
+      case value
+      when BaseModel
+        value.to_h
+      when Array
+        value.map { |item| serialize_value(item) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/administrate/client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Administrate
+  class Client
+    attr_reader :account, :users, :webhooks, :api_tokens, :clients,
+                :instances, :workflows, :executions, :sync_runs,
+                :llm_providers, :llm_projects, :llm_costs
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
+      config = Configuration.new(api_key: api_key, base_url: base_url, timeout: timeout, max_retries: max_retries)
+      transport = Transport.new(config)
+
+      @account = Resources::Account.new(transport)
+      @users = Resources::Users.new(transport)
+      @webhooks = Resources::Webhooks.new(transport)
+      @api_tokens = Resources::ApiTokens.new(transport)
+      @clients = Resources::Clients.new(transport)
+      @instances = Resources::Instances.new(transport)
+      @workflows = Resources::Workflows.new(transport)
+      @executions = Resources::Executions.new(transport)
+      @sync_runs = Resources::SyncRuns.new(transport)
+      @llm_providers = Resources::LlmProviders.new(transport)
+      @llm_projects = Resources::LlmProjects.new(transport)
+      @llm_costs = Resources::LlmCosts.new(transport)
+    end
+  end
+end

data/lib/administrate/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Administrate
+  DEFAULT_BASE_URL = 'https://administrate.dev'
+  API_VERSION = 'v1'
+  DEFAULT_TIMEOUT = 30
+  DEFAULT_MAX_RETRIES = 3
+
+  class Configuration
+    attr_reader :api_key, :base_url, :timeout, :max_retries
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
+      raise Administrate::Error, 'api_key is required' if api_key.nil? || api_key.empty?
+      raise Administrate::Error, "api_key must start with 'sk_live_'" unless api_key.start_with?('sk_live_')
+
+      @api_key = api_key
+      @base_url = base_url
+      @timeout = timeout
+      @max_retries = max_retries
+    end
+  end
+end