appnigma-sdk 0.1.0

data/lib/appnigma/constants.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Appnigma
+  KEY_PREFIX = "apn_live_"
+
+  # Where `Appnigma::Client.new` finds the key when none is passed.
+  KEY_ENV_NAME = "APPNIGMA_SDK_KEY"
+
+  # Where the client calls: production.
+  DEFAULT_BASE_URL = "https://engine.appnigma.ai"
+
+  # Points the client at a local or staging server for our own testing. Read
+  # from the environment, never a client setting, and never in the README: a
+  # customer always calls production.
+  API_URL_ENV_NAME = "APPNIGMA_API_URL"
+
+  # The only hosts the address may reach over plain http://, so a key never
+  # crosses a network unencrypted.
+  LOCAL_HOSTS = ["localhost", "127.0.0.1", "[::1]"].freeze
+
+  ROUTE_BASE = "/sdk/v1"
+
+  REQUEST_ID_HEADER = "x-request-id"
+  RETRY_AFTER_HEADER = "retry-after"
+
+  # How long one attempt may take before it counts as a network failure.
+  DEFAULT_TIMEOUT_MS = 30_000
+
+  # The same ceiling the TypeScript package applies, so the two READMEs show
+  # the same numbers.
+  MAX_TIMER_MS = 2_147_483_647
+
+  # Tries again after the first attempt: three attempts in all.
+  DEFAULT_MAX_RETRIES = 2
+
+  # A Retry-After longer than this is reported, not waited for.
+  DEFAULT_MAX_RETRY_WAIT_MS = 30_000
+
+  # This gem's own code for "no answer arrived". Not in the server's table,
+  # which only lists codes the server can send.
+  NETWORK_ERROR_CODE = "NETWORK_ERROR"
+
+  # The one 409 that sends an end customer through the connect flow again.
+  RECONNECT_ERROR_CODE = "CONNECTION_NEEDS_RECONNECT"
+
+  # An end customer id is 1 to 100 of letters, digits, dot, dash or underscore.
+  END_CUSTOMER_ID_PATTERN = /\A[A-Za-z0-9._-]{1,100}\z/
+  END_CUSTOMER_ID_RULE = "must be 1 to 100 characters: letters, digits, dot, dash or underscore"
+
+  # `.` and `..` fit the pattern but cannot travel in a URL path.
+  END_CUSTOMER_ID_PATH_UNSAFE = [".", ".."].freeze
+  END_CUSTOMER_ID_PATH_RULE = "cannot be only dots, it travels in the URL path"
+
+  # The server's error codes (the API description, 18.2). This gem keeps its
+  # own copy: it is published on its own. A test compares it with the
+  # TypeScript package's list.
+  ERROR_CODES = %w[
+    INVALID_INPUT
+    SDK_KEY_MISSING
+    SDK_KEY_INVALID
+    SDK_KEY_CANCELLED
+    MICROSERVER_NOT_ENABLED
+    PLATFORM_NOT_ENABLED
+    END_CUSTOMER_NOT_FOUND
+    FUNCTION_NOT_FOUND
+    CONNECTION_NEEDS_RECONNECT
+    RATE_LIMITED
+    PLATFORM_RATE_LIMITED
+    PLATFORM_ERROR
+    TIMED_OUT
+    LOGIC_FAILED
+    INTERNAL_ERROR
+    RECORD_NOT_FOUND
+    DATA_TYPE_NOT_AVAILABLE
+  ].freeze
+
+  OBJECTS = %w[contact company deal].freeze
+  CONNECTION_STATUSES = %w[connected needs_reconnect disconnected].freeze
+  PLATFORM_REQUEST_METHODS = %w[GET POST PUT PATCH DELETE].freeze
+end

data/lib/appnigma/crm.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "names"
+
+module Appnigma
+  # An end customer's CRM data in one shape, whichever CRM they use:
+  # `client.crm.contacts`, `client.crm.companies` and `client.crm.deals`,
+  # each with `list` and `get`. Reads, so they are retried.
+  class Crm
+    attr_reader :contacts, :companies, :deals
+
+    def initialize(client)
+      @contacts = Objects.new(client, list: :list_crm_contacts, get: :get_crm_contact)
+      @companies = Objects.new(client, list: :list_crm_companies, get: :get_crm_company)
+      @deals = Objects.new(client, list: :list_crm_deals, get: :get_crm_deal)
+    end
+
+    # The two reads of one CRM object.
+    class Objects
+      def initialize(client, list:, get:)
+        @client = client
+        @list = list
+        @get = get
+      end
+
+      # One page of records and a marker for the next; pass `next` as
+      # `cursor` for the following page. `limit` is 1 to 100.
+      def list(end_customer_id:, platform:, limit: nil, cursor: nil, timeout_ms: nil)
+        body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, limit: limit, cursor: cursor)
+        @client.call(@list, body, timeout_ms: timeout_ms)
+      end
+
+      # One record by its id in the CRM.
+      def get(end_customer_id:, platform:, id:, timeout_ms: nil)
+        body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, id: id)
+        @client.call(@get, body, timeout_ms: timeout_ms)
+      end
+    end
+  end
+end

data/lib/appnigma/errors.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+module Appnigma
+  # Every failure this gem raises, whether the server answered with an error
+  # or could not be reached at all. Rescue this for "anything from Appnigma",
+  # or one of the subclasses for one kind of failure. `code` is the string
+  # the server sent, known to this gem or not; `status` and `request_id` are
+  # nil when nothing came back.
+  class Error < StandardError
+    attr_reader :code, :status, :request_id, :details
+
+    def initialize(code:, message:, status: nil, request_id: nil, details: {})
+      super(message)
+      @code = code
+      @status = status
+      @request_id = request_id
+      @details = details
+    end
+  end
+
+  # 400. The server names each field it could not accept, as `problems`:
+  # a list of `{ field:, problem: }`. Also raised locally for a bad setting
+  # or a bad end customer id, before any call.
+  class InputError < Error
+    attr_reader :problems
+
+    def initialize(**args)
+      super
+      @problems = Errors.read_problems(details)
+    end
+  end
+
+  # 401 and 403, and a client started without a key.
+  class AuthError < Error; end
+
+  # 404.
+  class NotFoundError < Error; end
+
+  # 409 CONNECTION_NEEDS_RECONNECT: the end customer has to approve again.
+  class ReconnectError < Error; end
+
+  # Any other 409: the platform cannot give this yet.
+  class NotAvailableError < Error; end
+
+  # 429. `retry_after_seconds` is what the server's Retry-After header said,
+  # or nil when it sent none.
+  class RateLimitError < Error
+    attr_reader :retry_after_seconds
+
+    def initialize(retry_after_seconds: nil, **args)
+      super(**args)
+      @retry_after_seconds = retry_after_seconds
+    end
+  end
+
+  # Any 5xx, any status this gem does not know, and any answer that is not
+  # JSON. Our side is at fault, not the caller's input.
+  class ServerError < Error; end
+
+  # No answer arrived: the call failed, or the attempt ran out of time.
+  # `cause` is the underlying exception when there is one.
+  class NetworkError < Error
+    attr_reader :cause
+
+    def initialize(message:, cause: nil)
+      super(code: NETWORK_ERROR_CODE, message: message)
+      @cause = cause
+    end
+  end
+
+  # Turns one answer from the server into the error for its status. The type
+  # is chosen by status, not by code, so a code this gem has never seen still
+  # lands in the right class with its string kept.
+  module Errors
+    PROBLEM_KEYS = %w[field problem].freeze
+
+    # Every status the server's table names; any other is a ServerError. 409
+    # is chosen by code as well, in error_class.
+    CLASS_BY_STATUS = {
+      400 => InputError,
+      401 => AuthError,
+      403 => AuthError,
+      404 => NotFoundError,
+      429 => RateLimitError
+    }.freeze
+
+    module_function
+
+    def from_answer(status:, body:, request_id:, retry_after_seconds: nil)
+      fallback = "The Appnigma API answered #{status}"
+      shape = read_error_shape(body) || { code: "INTERNAL_ERROR", message: "", details: {} }
+      args = { code: shape[:code], message: shape[:message].empty? ? fallback : shape[:message],
+               status: status, request_id: request_id, details: shape[:details] }
+      klass = error_class(status, shape[:code])
+      klass == RateLimitError ? klass.new(retry_after_seconds: retry_after_seconds, **args) : klass.new(**args)
+    end
+
+    # Only CONNECTION_NEEDS_RECONNECT asks for a reconnect; any other 409 is
+    # something the platform cannot give yet.
+    def error_class(status, code)
+      return code == RECONNECT_ERROR_CODE ? ReconnectError : NotAvailableError if status == 409
+
+      CLASS_BY_STATUS.fetch(status, ServerError)
+    end
+
+    # Our shape is `{ "error" => { "code", "message", "details" } }`, as JSON
+    # parses it. Anything else reads as "not our shape".
+    def read_error_shape(body)
+      return nil unless body.is_a?(Hash) && body["error"].is_a?(Hash)
+
+      error = body["error"]
+      code = error["code"]
+      return nil unless code.is_a?(String) && !code.empty?
+
+      {
+        code: code,
+        message: error["message"].is_a?(String) ? error["message"] : "",
+        details: error["details"].is_a?(Hash) ? error["details"] : {}
+      }
+    end
+
+    def read_problems(details)
+      list = details["problems"]
+      return [] unless list.is_a?(Array)
+
+      list.filter_map do |entry|
+        next unless entry.is_a?(Hash) && PROBLEM_KEYS.all? { |key| entry[key].is_a?(String) }
+
+        { field: entry["field"], problem: entry["problem"] }
+      end
+    end
+  end
+end