attago 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 90446f07e1eb80c83339dfe22a11073a29d8407d8dd1339b602fa9aeb6cd53c3
+  data.tar.gz: aa45cf4c90dca3fbeb0be2816c5d6fd733f40c9d25ce428800c29fa9cb728d09
+SHA512:
+  metadata.gz: 5383151b402e020df0f63e70334e7e40d1e5e689edfbfbed9c245794d394d839bb9fdf9f8472795432943fcf5e5c2a6f9fdcc1adcc3258011f4be9d6bd29d901
+  data.tar.gz: 839aee72e606fdc9547eb040b111b027ace186636407b765f5d43656d8b31d1a716856da2cfab31ff5c47c09a1e4943fead6874e3ad069ecb9cebe65127b2906

data/README.md

@@ -0,0 +1,252 @@
+# attago
+
+[![CI](https://github.com/AttaGo/attago-rb-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/AttaGo/attago-rb-sdk/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/attago.svg)](https://badge.fury.io/rb/attago)
+
+Ruby SDK for the [AttaGo](https://attago.bid) crypto trading dashboard API.
+
+Go/No-Go crypto trading signals, alert subscriptions, x402 payments, webhook
+HMAC verification, and MCP JSON-RPC 2.0 -- **zero runtime dependencies**
+(stdlib only).
+
+## Install
+
+```ruby
+# Gemfile
+gem "attago"
+```
+
+Or:
+
+```bash
+gem install attago
+```
+
+Requires **Ruby 3.1+**.
+
+## Quick Start
+
+### API Key (agent endpoints)
+
+```ruby
+require "attago"
+
+client = Attago::Client.new(api_key: "ak_live_...")
+
+score = client.agent.get_score("BTC")
+puts score.composite.signal      # "GO", "NO-GO", or "NEUTRAL"
+puts score.composite.score       # 0-100
+puts score.composite.confidence  # 0.0-1.0
+
+client.close
+```
+
+### x402 Signer (pay-per-request)
+
+```ruby
+client = Attago::Client.new(signer: my_signer)
+
+# x402 payment handled transparently
+score = client.agent.get_score("ETH")
+data = client.agent.get_data("BTC", "ETH", "SOL")
+```
+
+### Cognito (account management)
+
+```ruby
+client = Attago::Client.new(
+  email: "user@example.com",
+  password: "...",
+  cognito_client_id: "abc123"
+)
+
+subs = client.subscriptions.list
+status = client.payments.status
+
+client.close
+```
+
+## Auth Modes
+
+Exactly one auth mode per client. Mix-and-match raises `ConfigError`.
+
+| Mode | Use Case | Endpoints |
+|------|----------|-----------|
+| `api_key:` | Scripts, bots, CI | Agent (score, data) |
+| `signer:` | Pay-per-request (x402) | Agent (score, data) |
+| `email: + password:` | Account management | Subscriptions, wallets, payments, webhooks, API keys, bundles, push, redeem |
+
+No auth is also valid -- public data endpoints only.
+
+## API Reference
+
+| Service | Methods |
+|---------|---------|
+| `client.agent` | `get_score(symbol)`, `get_data(*symbols)` |
+| `client.data` | `get_latest`, `get_token_data(token)`, `get_data_push(id)` |
+| `client.subscriptions` | `catalog`, `list`, `create(input)`, `update(id, input)`, `delete(id)` |
+| `client.payments` | `subscribe(input)`, `status`, `upgrade_quote(tier, cycle)` |
+| `client.wallets` | `register(input)`, `list`, `remove(address)` |
+| `client.webhooks` | `create(url)`, `list`, `delete(id)`, `send_test(opts)`, `send_server_test(id)` |
+| `client.mcp` | `initialize_session`, `list_tools`, `call_tool(name, args)`, `ping` |
+| `client.api_keys` | `create(name)`, `list`, `revoke(id)` |
+| `client.bundles` | `list`, `purchase(input)` |
+| `client.push` | `list`, `create(input)`, `delete(id)` |
+| `client.redeem` | `redeem(code)` |
+
+## Typed Inputs
+
+Service methods that accept structured input use typed structs:
+
+```ruby
+# Create a subscription
+input = Attago::SubscriptionCreateInput.new(
+  token_id: "BTC",
+  label: "BTC Price Alert",
+  groups: [
+    [Attago::Condition.new(
+      metric_name: "spotPrice",
+      threshold_op: "gte",
+      threshold_val: 100_000
+    )]
+  ],
+  cooldown_minutes: 60
+)
+sub = client.subscriptions.create(input)
+```
+
+```ruby
+# Register a wallet
+input = Attago::WalletRegisterInput.new(
+  wallet_address: "0x...",
+  chain: "base",
+  signature: "0x...",
+  timestamp: Time.now.utc.iso8601
+)
+wallet = client.wallets.register(input)
+```
+
+## Webhook Verification
+
+Verify incoming webhook signatures without a full client:
+
+```ruby
+body = request.body.read
+signature = request.headers["X-AttaGo-Signature"]
+secret = "whsec_..."
+
+if Attago::Webhooks.verify_signature(body, secret, signature)
+  payload = JSON.parse(body)
+  # Handle webhook
+else
+  # Invalid signature -- reject
+end
+```
+
+## Webhook Listener
+
+Standalone HTTP server for receiving webhooks in development or background
+workers:
+
+```ruby
+require "attago"
+
+listener = Attago::WebhookListener.new(secret: "whsec_...", port: 4000)
+
+listener.on_alert do |payload|
+  puts "#{payload.alert.token}: #{payload.alert.state}"
+end
+
+listener.on_test do |payload|
+  puts "Test webhook received"
+end
+
+listener.on_error do |err|
+  warn "Webhook error: #{err.message}"
+end
+
+listener.start  # Runs in a background thread
+# ... do other work ...
+listener.stop
+```
+
+## MCP (Model Context Protocol)
+
+JSON-RPC 2.0 over HTTP for AI agent integration:
+
+```ruby
+client = Attago::Client.new(api_key: "ak_live_...")
+
+info = client.mcp.initialize_session
+tools = client.mcp.list_tools
+
+result = client.mcp.call_tool("get_score", { "symbol" => "BTC" })
+puts result.content.first.text
+
+client.mcp.ping
+
+client.close
+```
+
+## Error Handling
+
+```ruby
+begin
+  score = client.agent.get_score("BTC")
+rescue Attago::PaymentRequiredError => e
+  puts "Payment required: #{e.message}"
+  puts "Requirements: #{e.payment_requirements}"
+rescue Attago::RateLimitError => e
+  puts "Rate limited, retry after: #{e.retry_after}s"
+rescue Attago::ApiError => e
+  puts "API error #{e.status_code}: #{e.message}"
+rescue Attago::McpError => e
+  puts "MCP error #{e.mcp_code}: #{e.mcp_message}"
+rescue Attago::AuthError => e
+  puts "Auth error: #{e.message}"
+rescue Attago::MfaRequiredError => e
+  puts "MFA required: #{e.challenge_name}"
+end
+```
+
+## Configuration
+
+```ruby
+client = Attago::Client.new(
+  api_key: "ak_live_...",
+  base_url: "https://staging.attago.io",  # Default: https://api.attago.bid
+)
+```
+
+## Testing
+
+The SDK ships with a `MockTransport` for unit testing your integrations:
+
+```ruby
+require "attago"
+
+transport = Attago::Testing::MockTransport.new do |req|
+  Attago::Testing::MockResponse.new(
+    code: 200,
+    body: { "token" => "BTC", "composite" => { "score" => 75, "signal" => "GO" } }
+  )
+end
+
+client = Attago::Client.new(api_key: "test", transport: transport)
+score = client.agent.get_score("BTC")
+assert_equal "GO", score.composite.signal
+```
+
+## Development
+
+```bash
+git clone git@github.com:AttaGo/attago-rb-sdk.git
+cd attago-rb-sdk
+bundle install
+
+# Run unit tests
+bundle exec rake test
+
+# Run conformance tests (requires live API)
+ATTAGO_BASE_URL=https://api.attago.bid ATTAGO_API_KEY=ak_... bundle exec rake conformance
+```

data/lib/attago/agent.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Attago
+  class AgentService
+    def initialize(client)
+      @client = client
+    end
+
+    # GET /agent/score?symbol=SYM
+    def get_score(symbol)
+      data = @client.request("GET", "/agent/score", params: { "symbol" => symbol })
+      AgentScoreResponse.from_hash(data)
+    end
+
+    # GET /agent/data?symbols=SYM1,SYM2 (omit for all)
+    def get_data(*symbols)
+      params = symbols.empty? ? {} : { "symbols" => symbols.join(",") }
+      data = @client.request("GET", "/agent/data", params: params)
+      AgentDataResponse.from_hash(data)
+    end
+  end
+end

data/lib/attago/api_keys.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Attago
+  class ApiKeyService
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /api-keys
+    def create(name)
+      data = @client.request("POST", "/user/api-keys", body: { "name" => name })
+      ApiKeyCreateResponse.from_hash(data)
+    end
+
+    # GET /api-keys
+    def list
+      data = @client.request("GET", "/user/api-keys")
+      (data["keys"] || []).map { |k| ApiKeyListItem.from_hash(k) }
+    end
+
+    # DELETE /api-keys/{key_id}
+    def revoke(key_id)
+      @client.request("DELETE", "/user/api-keys/#{URI.encode_www_form_component(key_id)}")
+      nil
+    end
+  end
+end

data/lib/attago/auth.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Attago
+  class CognitoAuth
+    # Allow injection of an HTTP client for testing.
+    attr_writer :http_client
+
+    def initialize(client_id:, region: DEFAULT_COGNITO_REGION, email: nil, password: nil)
+      @client_id = client_id
+      @region = region
+      @email = email
+      @password = password
+      @tokens = nil
+      @mu = Mutex.new  # Thread safety (GO-C1 audit lesson)
+      @http_client = nil
+    end
+
+    # Sign in and return tokens. Raises MfaRequiredError if MFA challenge.
+    def sign_in
+      resp = cognito_request("AWSCognitoIdentityProviderService.InitiateAuth", {
+        "AuthFlow" => "USER_PASSWORD_AUTH",
+        "ClientId" => @client_id,
+        "AuthParameters" => {
+          "USERNAME" => @email,
+          "PASSWORD" => @password
+        }
+      })
+
+      if resp["ChallengeName"]
+        raise MfaRequiredError.new(
+          session: resp["Session"],
+          challenge_name: resp["ChallengeName"]
+        )
+      end
+
+      tokens = parse_auth_result(resp["AuthenticationResult"])
+      @mu.synchronize { @tokens = tokens }
+      tokens
+    end
+
+    def sign_out
+      @mu.synchronize { @tokens = nil }
+    end
+
+    # Returns ID token, auto sign-in if needed.
+    def get_id_token
+      t = @mu.synchronize { @tokens }
+      if t.nil?
+        sign_in
+        t = @mu.synchronize { @tokens }
+      end
+      t.id_token
+    end
+
+    def set_tokens(tokens)
+      @mu.synchronize { @tokens = tokens }
+    end
+
+    def get_tokens
+      @mu.synchronize { @tokens }
+    end
+
+    # Respond to MFA challenge.
+    def respond_to_mfa(session, totp_code)
+      resp = cognito_request("AWSCognitoIdentityProviderService.RespondToAuthChallenge", {
+        "ChallengeName" => "SOFTWARE_TOKEN_MFA",
+        "ClientId" => @client_id,
+        "Session" => session,
+        "ChallengeResponses" => {
+          "USERNAME" => @email,
+          "SOFTWARE_TOKEN_MFA_CODE" => totp_code
+        }
+      })
+
+      tokens = parse_auth_result(resp["AuthenticationResult"])
+      @mu.synchronize { @tokens = tokens }
+      tokens
+    end
+
+    # Class-level methods (no instance needed)
+    def self.sign_up(email:, password:, client_id:, region: DEFAULT_COGNITO_REGION, http_client: nil)
+      auth = new(client_id: client_id, region: region)
+      auth.http_client = http_client if http_client
+      auth.send(:cognito_request, "AWSCognitoIdentityProviderService.SignUp", {
+        "ClientId" => client_id,
+        "Username" => email,
+        "Password" => password
+      })
+    end
+
+    def self.confirm_sign_up(email:, code:, client_id:, region: DEFAULT_COGNITO_REGION, http_client: nil)
+      auth = new(client_id: client_id, region: region)
+      auth.http_client = http_client if http_client
+      auth.send(:cognito_request, "AWSCognitoIdentityProviderService.ConfirmSignUp", {
+        "ClientId" => client_id,
+        "Username" => email,
+        "ConfirmationCode" => code
+      })
+    end
+
+    def self.forgot_password(email:, client_id:, region: DEFAULT_COGNITO_REGION, http_client: nil)
+      auth = new(client_id: client_id, region: region)
+      auth.http_client = http_client if http_client
+      auth.send(:cognito_request, "AWSCognitoIdentityProviderService.ForgotPassword", {
+        "ClientId" => client_id,
+        "Username" => email
+      })
+    end
+
+    def self.confirm_forgot_password(email:, code:, new_password:, client_id:, region: DEFAULT_COGNITO_REGION, http_client: nil)
+      auth = new(client_id: client_id, region: region)
+      auth.http_client = http_client if http_client
+      auth.send(:cognito_request, "AWSCognitoIdentityProviderService.ConfirmForgotPassword", {
+        "ClientId" => client_id,
+        "Username" => email,
+        "ConfirmationCode" => code,
+        "Password" => new_password
+      })
+    end
+
+    private
+
+    def parse_auth_result(result)
+      CognitoTokens.new(
+        id_token: result["IdToken"],
+        access_token: result["AccessToken"],
+        refresh_token: result["RefreshToken"]
+      )
+    end
+
+    def cognito_request(target, body)
+      if @http_client
+        # Use injected HTTP client for testing
+        resp = @http_client.call(target, body)
+      else
+        uri = URI.parse("https://cognito-idp.#{@region}.amazonaws.com/")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = 10
+        http.read_timeout = 15
+
+        req = Net::HTTP::Post.new("/")
+        req["Content-Type"] = "application/x-amz-json-1.1"
+        req["X-Amz-Target"] = target
+        req.body = JSON.generate(body)
+
+        resp = http.request(req)
+      end
+
+      # Check HTTP status BEFORE JSON decode (GO audit I3 lesson)
+      unless resp.code.to_i == 200
+        begin
+          err_body = JSON.parse(resp.body || "")
+          err_type = err_body["__type"]&.split("#")&.last || "UnknownError"
+          err_msg = err_body["message"] || err_body["Message"] || "Authentication failed"
+        rescue JSON::ParserError
+          err_type = "UnknownError"
+          err_msg = "HTTP #{resp.code}"
+        end
+        raise AuthError.new(err_msg, code: err_type)
+      end
+
+      JSON.parse(resp.body)
+    end
+  end
+end

data/lib/attago/bundles.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Attago
+  class BundleService
+    def initialize(client)
+      @client = client
+    end
+
+    # GET /api/bundles
+    def list
+      data = @client.request("GET", "/api/bundles")
+      BundleListResponse.from_hash(data)
+    end
+
+    # POST /api/bundles
+    def purchase(input)
+      body = { "bundleIndex" => input.bundle_index, "walletAddress" => input.wallet_address }
+      data = @client.request("POST", "/api/bundles", body: body)
+      BundlePurchaseResponse.from_hash(data)
+    end
+  end
+end