apollo-deploy-signal-sdk 1.0.5

data/lib/apollo-deploy-signal-sdk.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "apollo_deploy_signal_sdk"

data/lib/apollo_deploy_signal_sdk/client.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+require_relative "resources/emails"
+require_relative "resources/metrics"
+require_relative "resources/suppressions"
+require_relative "resources/segments"
+require_relative "resources/topics"
+require_relative "resources/contact-properties"
+require_relative "resources/contacts"
+require_relative "resources/webhooks"
+require_relative "resources/api-keys"
+require_relative "resources/projects"
+require_relative "resources/sending-domains"
+
+module ApolloDeploySignalSdk
+  # Configuration for the Apollo Signal API SDK client.
+  class Config
+    # @return [String] the base URL for API requests
+    attr_accessor :base_url
+    # @return [Integer] request timeout in seconds
+    attr_accessor :timeout
+    # @return [Hash] retry configuration
+    attr_accessor :retries
+    # @return [Hash] default headers sent with every request
+    attr_accessor :default_headers
+    # @return [Boolean] whether POST/PATCH requests may be retried without an idempotency key
+    attr_accessor :retry_unsafe_requests
+
+    # @param base_url [String] the base URL for API requests
+    # @param timeout [Integer] request timeout in seconds (default: 15)
+    # @param retries [Hash] retry configuration
+    # @param default_headers [Hash] headers sent with every request
+    def initialize(
+      base_url: "https://signal.apollodeploy.com",
+      timeout: 15,
+      retries: { attempts: 3, backoff: 0.4, jitter: true, max_backoff: 30.0 },
+      default_headers: {},
+      retry_unsafe_requests: false,
+      **_
+    )
+      @base_url = base_url
+      @timeout = timeout
+      @retries = retries
+      @default_headers = default_headers
+      @retry_unsafe_requests = retry_unsafe_requests
+    end
+  end
+
+  # Main client for the Apollo Signal API API.
+  #
+  # Provides access to all API domains as instance methods.
+  class Client
+    # @return [ApolloDeploySignalSdk::Emails]
+    attr_reader :emails
+    # @return [ApolloDeploySignalSdk::Metrics]
+    attr_reader :metrics
+    # @return [ApolloDeploySignalSdk::Suppressions]
+    attr_reader :suppressions
+    # @return [ApolloDeploySignalSdk::Segments]
+    attr_reader :segments
+    # @return [ApolloDeploySignalSdk::Topics]
+    attr_reader :topics
+    # @return [ApolloDeploySignalSdk::ContactProperties]
+    attr_reader :contactProperties
+    # @return [ApolloDeploySignalSdk::Contacts]
+    attr_reader :contacts
+    # @return [ApolloDeploySignalSdk::Webhooks]
+    attr_reader :webhooks
+    # @return [ApolloDeploySignalSdk::ApiKeys]
+    attr_reader :apiKeys
+    # @return [ApolloDeploySignalSdk::Projects]
+    attr_reader :projects
+    # @return [ApolloDeploySignalSdk::SendingDomains]
+    attr_reader :sendingDomains
+
+    # @return [ApolloDeploySignalSdk::Config] the client configuration
+    attr_reader :config
+
+    # @return [ApolloDeploySignalSdk::Transport] the underlying HTTP transport
+    attr_reader :transport
+
+    # Create a new API client.
+    #
+    # @param config [ApolloDeploySignalSdk::Config, Hash, nil]
+    #   Either a Config instance or keyword arguments matching Config#initialize.
+    def initialize(config = nil)
+      @config = if config.is_a?(Config)
+                  config
+                elsif config.is_a?(Hash)
+                  Config.new(**config)
+                else
+                  Config.new
+                end
+
+      @transport = Transport.new(@config)
+
+      @emails = ApolloDeploySignalSdk::Emails.new(@transport)
+      @metrics = ApolloDeploySignalSdk::Metrics.new(@transport)
+      @suppressions = ApolloDeploySignalSdk::Suppressions.new(@transport)
+      @segments = ApolloDeploySignalSdk::Segments.new(@transport)
+      @topics = ApolloDeploySignalSdk::Topics.new(@transport)
+      @contactProperties = ApolloDeploySignalSdk::ContactProperties.new(@transport)
+      @contacts = ApolloDeploySignalSdk::Contacts.new(@transport)
+      @webhooks = ApolloDeploySignalSdk::Webhooks.new(@transport)
+      @apiKeys = ApolloDeploySignalSdk::ApiKeys.new(@transport)
+      @projects = ApolloDeploySignalSdk::Projects.new(@transport)
+      @sendingDomains = ApolloDeploySignalSdk::SendingDomains.new(@transport)
+    end
+  end
+end

data/lib/apollo_deploy_signal_sdk/errors.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module ApolloDeploySignalSdk
+  # Structured error raised on API and network failures.
+  #
+  # Inherits from StandardError and provides structured access to error
+  # details including status code, error code, request ID, and convenience
+  # methods for common error classifications.
+  #
+  # @example Basic error handling
+  #   begin
+  #     client.users.get_user(id: "123")
+  #   rescue ApolloDeploySignalSdk::SDKError => e
+  #     puts "Error #{e.status}: #{e.message} (#{e.code})"
+  #     puts "Request ID: #{e.request_id}" if e.request_id
+  #
+  #     if e.rate_limited?
+  #       sleep 1
+  #       retry
+  #     end
+  #
+  #     if e.server_error?
+  #       # Log and alert
+  #     end
+  #   end
+  class SDKError < StandardError
+    # @return [String] machine-readable error code (e.g. "not_found", "rate_limit_exceeded")
+    attr_reader :code
+
+    # @return [Integer] HTTP status code (0 for network errors)
+    attr_reader :status
+
+    # @return [String, nil] unique request identifier from the server
+    attr_reader :request_id
+
+    # @return [String, nil] ISO 8601 timestamp of error occurrence
+    attr_reader :timestamp
+
+    # @return [String, nil] request path that caused the error
+    attr_reader :path
+
+    # @return [String, nil] HTTP method that caused the error
+    attr_reader :method
+
+    # @return [String, nil] helpful hint for resolving the error
+    attr_reader :hint
+
+    # @return [Hash, nil] structured error details
+    attr_reader :details
+
+    # Create a new SDKError.
+    #
+    # @param message [String] human-readable error message
+    # @param status [Integer] HTTP status code (0 for network errors)
+    # @param code [String] machine-readable error code
+    # @param request_id [String, nil] server-provided request ID
+    # @param timestamp [String, nil] error timestamp
+    # @param path [String, nil] request path
+    # @param method [String, nil] HTTP method
+    # @param hint [String, nil] resolution hint
+    # @param details [Hash, nil] structured error details
+    def initialize(
+      message,
+      status = 0,
+      code = "unknown_error",
+      request_id: nil,
+      timestamp: nil,
+      path: nil,
+      method: nil,
+      hint: nil,
+      details: nil
+    )
+      super(message)
+
+      @code = code
+      @status = status
+      @request_id = request_id
+      @timestamp = timestamp
+      @path = path
+      @method = method
+      @hint = hint
+      @details = details
+    end
+
+    # @return [Boolean] true if the error is a rate limit (HTTP 429)
+    def rate_limited?
+      @code == "rate_limit_exceeded" || @status == 429
+    end
+
+    # @return [Boolean] true if the error is authentication-related
+    def auth_error?
+      %w[unauthorized credential_expired credential_revoked].include?(@code)
+    end
+
+    # @return [Boolean] true if the error is a permission error (HTTP 403)
+    def forbidden?
+      @code == "forbidden" || @status == 403
+    end
+
+    # @return [Boolean] true if the resource was not found (HTTP 404)
+    def not_found?
+      @code == "not_found" || @status == 404
+    end
+
+    # @return [Boolean] true if the error is a validation error
+    def validation_error?
+      %w[validation_failed request_validation_failed bad_request unprocessable_entity].include?(@code) ||
+        @status == 422
+    end
+
+    # @return [Boolean] true if status is 5xx (server error)
+    def server_error?
+      @status >= 500
+    end
+
+    # @return [Boolean] true if status is 4xx (client error)
+    def client_error?
+      @status >= 400 && @status < 500
+    end
+
+    # @return [Boolean] true if this error is safe to retry
+    def retryable?
+      @code == "network_error" ||
+        @code == "gateway_timeout" ||
+        [408, 425, 429].include?(@status) ||
+        @status >= 500
+    end
+
+    # @return [Hash] a hash representation for logging and serialization
+    def to_h
+      {
+        name: "SDKError",
+        message: message,
+        status: @status,
+        code: @code,
+        request_id: @request_id,
+        timestamp: @timestamp,
+        path: @path,
+        method: @method,
+        hint: @hint,
+        details: @details
+      }.compact
+    end
+
+    # @return [String] JSON representation for logging
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end

data/lib/apollo_deploy_signal_sdk/resources/api-keys.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../transport"
+require_relative "../errors"
+
+module ApolloDeploySignalSdk
+  # apiKeys API domain
+  class ApiKeys
+    attr_reader :transport
+
+    def initialize(transport)
+      @transport = transport
+    end
+
+    # @param project_id [String]
+    # @raise [ApolloDeploySignalSdk::SDKError]
+    # @return [ListApiKeysResponse]
+    def list_api_keys(project_id:)
+      path_params = {
+        "projectId" => project_id,
+      }
+
+      transport.request(
+        method: :get,
+        path: "/v1/projects/${projectId}/api-keys",
+        path_params: path_params,
+        timeout_ms: nil,
+      )
+    end
+
+    # @param project_id [String]
+    # @param key_id [String]
+    # @raise [ApolloDeploySignalSdk::SDKError]
+    # @return [ApiKey]
+    def get_api_key(project_id:, key_id:)
+      path_params = {
+        "projectId" => project_id,
+        "keyId" => key_id,
+      }
+
+      transport.request(
+        method: :get,
+        path: "/v1/projects/${projectId}/api-keys/${keyId}",
+        path_params: path_params,
+        timeout_ms: nil,
+      )
+    end
+
+    # @param project_id [String]
+    # @param key_id [String]
+    # @raise [ApolloDeploySignalSdk::SDKError]
+    # @return [ApiKeyUsageResponse]
+    def get_api_key_usage(project_id:, key_id:)
+      path_params = {
+        "projectId" => project_id,
+        "keyId" => key_id,
+      }
+
+      transport.request(
+        method: :get,
+        path: "/v1/projects/${projectId}/api-keys/${keyId}/usage",
+        path_params: path_params,
+        timeout_ms: nil,
+      )
+    end
+
+    # @param project_id [String]
+    # @param key_id [String]
+    # @raise [ApolloDeploySignalSdk::SDKError]
+    # @return [nil]
+    def export_api_key_usage(project_id:, key_id:)
+      path_params = {
+        "projectId" => project_id,
+        "keyId" => key_id,
+      }
+
+      transport.request(
+        method: :get,
+        path: "/v1/projects/${projectId}/api-keys/${keyId}/usage/export",
+        path_params: path_params,
+        timeout_ms: nil,
+      )
+    end
+
+  end
+end

data/lib/apollo_deploy_signal_sdk/resources/contact-properties.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "../transport"
+require_relative "../errors"
+
+module ApolloDeploySignalSdk
+  # contactProperties API domain
+  class ContactProperties
+    attr_reader :transport
+
+    def initialize(transport)
+      @transport = transport
+    end
+
+    # @param project_id [String]
+    # @raise [ApolloDeploySignalSdk::SDKError]
+    # @return [ContactPropertyPageResponse]
+    def list_contact_properties(project_id:)
+      path_params = {
+        "projectId" => project_id,
+      }
+
+      transport.request(
+        method: :get,
+        path: "/v1/projects/${projectId}/contact-properties",
+        path_params: path_params,
+        timeout_ms: nil,
+      )
+    end
+
+    # @param project_id [String]
+    # @param property_id [String]
+    # @raise [ApolloDeploySignalSdk::SDKError]
+    # @return [ContactPropertyResponse]
+    def get_contact_property(project_id:, property_id:)
+      path_params = {
+        "projectId" => project_id,
+        "propertyId" => property_id,
+      }
+
+      transport.request(
+        method: :get,
+        path: "/v1/projects/${projectId}/contact-properties/${propertyId}",
+        path_params: path_params,
+        timeout_ms: nil,
+      )
+    end
+
+    # @param project_id [String]
+    # @param body [CreateContactPropertyBody] request body
+    # @raise [ApolloDeploySignalSdk::SDKError]
+    # @return [ContactPropertyResponse]
+    def create_contact_property(project_id:, body:)
+      path_params = {
+        "projectId" => project_id,
+      }
+
+      transport.request(
+        method: :post,
+        path: "/v1/projects/${projectId}/contact-properties",
+        path_params: path_params,
+        body: body,
+        content_type: "application/json",
+        timeout_ms: nil,
+      )
+    end
+
+    # @param project_id [String]
+    # @param property_id [String]
+    # @param body [UpdateContactPropertyBody] request body
+    # @raise [ApolloDeploySignalSdk::SDKError]
+    # @return [ContactPropertyResponse]
+    def update_contact_property(project_id:, property_id:, body:)
+      path_params = {
+        "projectId" => project_id,
+        "propertyId" => property_id,
+      }
+
+      transport.request(
+        method: :patch,
+        path: "/v1/projects/${projectId}/contact-properties/${propertyId}",
+        path_params: path_params,
+        body: body,
+        content_type: "application/json",
+        timeout_ms: nil,
+      )
+    end
+
+    # @param project_id [String]
+    # @param property_id [String]
+    # @raise [ApolloDeploySignalSdk::SDKError]
+    # @return [nil]
+    def delete_contact_property(project_id:, property_id:)
+      path_params = {
+        "projectId" => project_id,
+        "propertyId" => property_id,
+      }
+
+      transport.request(
+        method: :delete,
+        path: "/v1/projects/${projectId}/contact-properties/${propertyId}",
+        path_params: path_params,
+        timeout_ms: nil,
+      )
+    end
+
+  end
+end